diff options
87 files changed, 76107 insertions, 2010 deletions
@@ -196,13 +196,60 @@ ./doxygen/aliases ./doxygen/Doxyfile.in +./doxygen/dox/About.dox +./doxygen/dox/Cookbook.dox +./doxygen/dox/DDLBNF110.dox +./doxygen/dox/FileFormatSpec.dox +./doxygen/dox/GettingStarted.dox +./doxygen/dox/H5AC_cache_config_t.dox +./doxygen/dox/H5Acreate.dox +./doxygen/dox/H5Aiterate.dox +./doxygen/dox/MetadataCachingInHDF5.dox +./doxygen/dox/OtherSpecs.dox +./doxygen/dox/Overview.dox +./doxygen/dox/ReferenceManual.dox +./doxygen/dox/Specifications.dox +./doxygen/dox/TechnicalNotes.dox ./doxygen/dox/api-compat-macros.dox -./doxygen/dox/mainpage.dox ./doxygen/dox/rm-template.dox +./doxygen/examples/FF-IH_FileGroup.gif +./doxygen/examples/FF-IH_FileObject.gif +./doxygen/examples/FileFormatSpecChunkDiagram.jpg +./doxygen/examples/H5Pset_metadata_read_attempts.c +./doxygen/examples/H5Pset_object_flush_cb.c +./doxygen/examples/H5.format.1.0.html +./doxygen/examples/H5.format.1.1.html +./doxygen/examples/H5.format.2.0.html +./doxygen/examples/H5.format.html +./doxygen/examples/H5A_examples.c +./doxygen/examples/H5D_examples.c ./doxygen/examples/H5Fclose.c ./doxygen/examples/H5Fcreate.c +./doxygen/examples/H5F_examples.c +./doxygen/examples/H5Pget_metadata_read_attempts.1.c +./doxygen/examples/H5Pget_metadata_read_attempts.2.c +./doxygen/examples/H5Pget_metadata_read_attempts.3.c +./doxygen/examples/H5Pget_object_flush_cb.c +./doxygen/examples/ImageSpec.html +./doxygen/examples/PaletteExample1.gif +./doxygen/examples/Palettes.fm.anc.gif +./doxygen/examples/TableSpec.html +./doxygen/examples/ThreadSafeLibrary.html +./doxygen/examples/VFL.html ./doxygen/examples/hello_hdf5.c +./doxygen/hdf5_footer.html +./doxygen/hdf5_header.html +./doxygen/hdf5_navtree_hacks.js +./doxygen/hdf5doxy.css +./doxygen/hdf5doxy_layout.xml +./doxygen/img/FF-IH_FileGroup.gif +./doxygen/img/FF-IH_FileObject.gif +./doxygen/img/FileFormatSpecChunkDiagram.jpg ./doxygen/img/HDFG-logo.png +./doxygen/img/PaletteExample1.gif +./doxygen/img/Palettes.fm.anc.gif +./doxygen/img/ftv2node.png +./doxygen/img/ftv2pnode.png ./examples/Attributes.txt ./examples/Makefile.am diff --git a/doxygen/aliases b/doxygen/aliases index ca937b4..cf74a71 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -195,5 +195,4 @@ ALIASES += scopes="<table><tr><td>#H5F_SCOPE_GLOBAL</td><td>Flushes the entire v ALIASES += sign_prop="<table><tr><td>#H5T_SGN_NONE</td><td>0</td><td>Unsigned integer type</td></tr><tr><td>#H5T_SGN_2</td><td>1</td><td>Two's complement signed integer type</td></tr></table>" ALIASES += storage_type="<table><tr><td>#H5G_STORAGE_TYPE_COMPACT</td><td>Compact storage</td></tr><tr><td>#H5G_STORAGE_TYPE_DENSE</td><td>Indexed storage</td></tr><tr><td>#H5G_STORAGE_TYPE_SYMBOL_TABLE</td><td>Symbol tables, the original HDF5 structure</td></tr></table>" ALIASES += str_pad_type="<table><tr><td>#H5T_STR_NULLTERM</td><td>0</td><td>Null terminate (as C does)</td></tr><tr><td>#H5T_STR_NULLPAD</td><td>1</td><td>Pad with zeros</td></tr><tr><td>#H5T_STR_SPACEPAD</td><td>2</td><td>Pad with spaces (as FORTRAN does)</td></tr></table>" -ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()" ALIASES += obj_info_fields="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td>#H5O_INFO_BASIC</td><td>Fill in the fileno, addr, type, and rc fields</td></tr><tr> <td>#H5O_INFO_TIME</td><td>Fill in the atime, mtime, ctime, and btime fields</td></tr><tr> <td>#H5O_INFO_NUM_ATTRS</td> <td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_HDR</td><td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_META_SIZE</td><td>Fill in the meta_size field</td></tr><tr><td>#H5O_INFO_ALL</td><td>#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE</td></tr></table>" diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox new file mode 100644 index 0000000..3be9202 --- /dev/null +++ b/doxygen/dox/About.dox @@ -0,0 +1,11 @@ +/** \page About About + +The implementation of this documentation set is based on the fantastic work of the +<a href="https://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen project</a>. +Please refer to their <a href="https://gitlab.com/libeigen/eigen">GitLab repository</a> +and the online version of their +<a href="http://eigen.tuxfamily.org/dox/">Doxygen-based documentation</a>. +Not only does Eigen set a standard as a piece of software, but also as an example +of <em>documentation done right</em>. + +*/
\ No newline at end of file diff --git a/doxygen/dox/Cookbook.dox b/doxygen/dox/Cookbook.dox new file mode 100644 index 0000000..4abc896 --- /dev/null +++ b/doxygen/dox/Cookbook.dox @@ -0,0 +1,5 @@ +/** \page Cookbook Cookbook + + Healthy, everyday recipes for every taste and budget... + + */
\ No newline at end of file diff --git a/doxygen/dox/DDLBNF110.dox b/doxygen/dox/DDLBNF110.dox new file mode 100644 index 0000000..f7e4267 --- /dev/null +++ b/doxygen/dox/DDLBNF110.dox @@ -0,0 +1,650 @@ +/** \page DDLBNF110 DDL in BNF through HDF5 1.10 + +\todo Revise this & break it up! + +\section intro110 Introduction + +This document contains the data description language (DDL) for an HDF5 file. The +description is in Backus-Naur Form (BNF). + +\section expo110 Explanation of Symbols + +This section contains a brief explanation of the symbols used in the DDL. + +\code{.unparsed} +::= defined as + <tname> a token with the name tname + <a> | <b> one of <a> or <b> + <a>opt zero or one occurrence of <a> + <a>* zero or more occurrence of <a> + <a>+ one or more occurrence of <a> + [0-9] an element in the range between 0 and 9 + '[' the token within the quotes (used for special characters) + TBD To Be Decided +\endcode + +\section ddl110 The DDL + +\code{.unparsed} +<file> ::= HDF5 <file_name> { <file_super_block>opt <root_group> } + +<file_name> ::= <identifier> + +<file_super_block> ::= SUPER_BLOCK { + SUPERBLOCK_VERSION <int_value> + FREELIST_VERSION <int_value> + SYMBOLTABLE_VERSION <int_value> + OBJECTHEADER_VERSION <int_value> + OFFSET_SIZE <int_value> + LENGTH_SIZE <int_value> + BTREE_RANK <int_value> + BTREE_LEAF <int_value> + ISTORE_K <int_value> + <super_block_filespace> + USER_BLOCK { + USERBLOCK_SIZE <int_value> + } + } + +<super_block_filespace> ::= FILE_SPACE_STRATEGY <super_block_strategy> + FREE_SPACE_PERSIST <boolean_value> + FREE_SPACE_SECTION_THRESHOLD <int_value> + FILE_SPACE_PAGE_SIZE <int_value> + +<super_block_strategy> ::= H5F_FSPACE_STRATEGY_FSM_AGGR | H5F_FSPACE_STRATEGY_PAGE | + H5F_FSPACE_STRATEGY_AGGR | H5F_FSPACE_STRATEGY_NONE | + Unknown strategy + +<root_group> ::= GROUP "/" { + <anon_named_datatype>* + <object_id>opt + <group_comment>opt + <group_attribute>* + <group_member>* + } + +<datatype> ::= <atomic_type> | <compound_type> | <variable_length_type> | <array_type> + +<anon_named_datatype> ::= DATATYPE <anon_named_type_name> { + <datatype> + } + +<anon_named_type_name> ::= the assigned name for anonymous named type is + in the form of #oid, where oid is the object id + of the type + +<atomic_type> ::= <integer> | <float> | <time> | <string> | + <bitfield> | <opaque> | <reference> | <enum> + +<boolean_value> ::= FALSE | TRUE + +<integer> ::= H5T_STD_I8BE | H5T_STD_I8LE | + H5T_STD_I16BE | H5T_STD_I16LE | + H5T_STD_I32BE | H5T_STD_I32LE | + H5T_STD_I64BE | H5T_STD_I64LE | + H5T_STD_U8BE | H5T_STD_U8LE | + H5T_STD_U16BE | H5T_STD_U16LE | + H5T_STD_U32BE | H5T_STD_U32LE | + H5T_STD_U64BE | H5T_STD_U64LE | + H5T_NATIVE_CHAR | H5T_NATIVE_UCHAR | + H5T_NATIVE_SHORT | H5T_NATIVE_USHORT | + H5T_NATIVE_INT | H5T_NATIVE_UINT | + H5T_NATIVE_LONG | H5T_NATIVE_ULONG | + H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG + +<float> ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE | + H5T_IEEE_F64BE | H5T_IEEE_F64LE | + H5T_NATIVE_FLOAT | H5T_NATIVE_DOUBLE | + H5T_NATIVE_LDOUBLE + +<time> ::= H5T_TIME: not yet implemented + +<string> ::= H5T_STRING { + STRSIZE <strsize>; + STRPAD <strpad>; + CSET <cset>; + CTYPE <ctype>; + } + +<strsize> ::= <int_value> + +<strpad> ::= H5T_STR_NULLTERM | H5T_STR_NULLPAD | H5T_STR_SPACEPAD + +<cset> ::= H5T_CSET_ASCII | H5T_CSET_UTF8 + +<ctype> ::= H5T_C_S1 | H5T_FORTRAN_S1 + +<bitfield> ::= H5T_STD_B8BE | H5T_STD_B8LE | + H5T_STD_B16BE | H5T_STD_B16LE | + H5T_STD_B32BE | H5T_STD_B32LE | + H5T_STD_B64BE | H5T_STD_B64LE + +<opaque> ::= H5T_OPAQUE { + OPAQUE_TAG <identifier>; + OPAQUE_SIZE <int_value>;opt + } + +<reference> ::= H5T_REFERENCE { <ref_type> } + +<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG | H5T_STD_REF | UNDEFINED + +<compound_type> ::= H5T_COMPOUND { + <member_type_def>+ + } + +<member_type_def> ::= <datatype> <field_name>; + +<field_name> ::= <identifier> + +<variable_length_type> ::= H5T_VLEN { <datatype> } + +<array_type> ::= H5T_ARRAY { <dim_sizes> <datatype> } + +<dim_sizes> ::= '['<dimsize>']' | '['<dimsize>']'<dim_sizes> + +<dimsize> ::= <int_value> + +<attribute> ::= ATTRIBUTE <attr_name> { + <dataset_type> + <dataset_space> + <data>opt + } + +<attr_name> ::= <identifier> + +<dataset_type> ::= DATATYPE <path_name> | <datatype> + +<enum> ::= H5T_ENUM { + <enum_base_type> <enum_def>+ + } + +<enum_base_type> ::= <integer> +// Currently enums can only hold integer type data, but they may be expanded +// in the future to hold any datatype + +<enum_def> ::= <enum_symbol> <enum_val>; + +<enum_symbol> ::= <identifier> + +<enum_val> ::= <int_value> + +<path_name> ::= <path_part>+ + +<path_part> ::= /<identifier> + +<dataspace> ::= <scalar_space> | <simple_space> | <complex_space> | <null_space> + +<null_space> ::= NULL + +<scalar_space> ::= SCALAR + +<simple_space> ::= SIMPLE { <current_dims> / <max_dims> } + +<complex_space> ::= COMPLEX { <complex_space_definition> } + +<dataset_space> ::= DATASPACE <path_name> | <dataspace> + +<current_dims> ::= <dims> + +<max_dims> ::= '(' <max_dim_list> ')' + +<max_dim_list> ::= <max_dim> | <max_dim>, <max_dim_list> + +<max_dim> ::= <int_value> | H5S_UNLIMITED + +<data> ::= <subset> | <data_values> + +<data_values> ::= DATA { + <scalar_space_data> | <simple_space_data> + } + +<scalar_space_data> ::= <any_element> + +<any_element> ::= <atomic_element> | <compound_element> | + <variable_length_element> | <array_element> + +<any_data_seq> ::= <any_element> | <any_element>, <any_data_seq> + +<atomic_element> :: = <integer_data> | <float_data> | <time_data> | + <string_data> | <bitfield_data> | <opaque_data> | + <enum_data> | <reference_data> + +<subset> ::= SUBSET { + <start>; + <stride>; + <count>; + <block>; + DATA { + <simple_space_data> + } + } + +<start> ::= START (<coor_list>) + +<stride> ::= STRIDE (<pos_list>) + +<count> ::= COUNT (<max_dim_list>) + +<block> ::= BLOCK (<max_dim_list>) + +<coor_list> ::= <coor_data>, <coor_list> | <coor_data> + +<coor_data> ::= <integer_data> | H5S_UNLIMITED + +<integer_data> ::= <int_value> + +<float_data> ::= a floating point number + +<time_data> ::= DATA{ not yet implemented.} + +<string_data> ::= a string +// A string is enclosed in double quotes. +// If a string is displayed on more than one line, string concatenate +// operator '//'is used. + +<bitfield_data> ::= <hex_value> + +<opaque_data> ::= <hex_value>:<hex_value> | <hex_value> + +<enum_data> ::= <enum_symbol> + +<reference_data> ::= <object_ref_data> | <data_region_data> | <attribute_data> | NULL + +<object_ref_data> ::= <object_type> <object_num> + +<object_type> ::= DATASET | GROUP | DATATYPE + +<object_id> ::= OBJECTID { <object_num> } + +<object_num> ::= <int_value>:<int_value> | <int_value> + +<attribute_data> ::= ATTRIBUTE <attr_name> + +<data_region_data> ::= DATASET <dataset_name> { + <data_region_type>opt <data_region_data_list> + <dataset_type>opt <dataset_space>opt + <data>opt + } + +<data_region_type> ::= REGION_TYPE <data_region_data_type> + +<data_region_data_type> ::= POINT | BLOCK + +<data_region_data_list> ::= <data_region_data_info>, <data_region_data_list> | + <data_region_data_info> + +<data_region_data_info> ::= <region_info> | <point_info> + +<region_info> ::= (<lower_region_vals>)-(<upper_region_vals>) + +<lower_region_vals> ::= <lower_bound>, <lower_region_vals> | <lower_bound> + +<upper_region_vals> ::= <upper_bound>, <upper_region_vals> | <upper_bound> + +<lower_bound> ::= <int_value> + +<upper_bound> ::= <int_value> + +<point_info> ::= (<point_vals>) + +<point_vals> ::= <int_value> | <int_value>, <point_vals> + +<compound_element> ::= { <any_data_seq> } + +<atomic_simple_data> :: = <atomic_element>, <atomic_simple_data> | + <atomic_element> + +<simple_space_data> :: = <any_data_seq> + +<variable_length_element> ::= ( <any_data_seq> ) + +<array_element> ::= '[' <any_data_seq> ']' + +<named_datatype> ::= DATATYPE <type_name> { <datatype> } + +<type_name> ::= <identifier> + +<hardlink> ::= HARDLINK <path_name> + +<group> ::= GROUP <group_name> { <hardlink> | <group_info> } + +<group_comment> ::= COMMENT <string_data> + +<group_name> ::= <identifier> + +<group_info> ::= <object_id>opt <group_comment>opt <group_attribute>* + <group_member>* + +<group_attribute> ::= <attribute> + +<group_member> ::= <named_datatype> | <group> | <dataset> | + <softlink> | <external_link> + +<dataset> ::= DATASET <dataset_name> { <hardlink> | <dataset_info> } + +<dataset_info> ::= <dataset_type> + <dataset_space> + <dcpl_info>opt + <dataset_attribute>* <object_id>opt + <data>opt +// Tokens above can be in any order as long as <data> is +// after <dataset_type> and <dataset_space>. + +<dcpl_info> ::= <storagelayout> + <compression_filters> + <fillvalue> + <allocationtime> + +<dataset_name> ::= <identifier> + +<storagelayout> :: = STORAGE_LAYOUT { + <contiguous_layout> | <chunked_layout> | + <compact_layout> | <virtual_layout> + } + +<contiguous_layout> ::= CONTIGUOUS + <internal_layout> | <external_layout> + +<chunked_layout> ::= CHUNKED <dims> + <filter_ratio>opt + +<compact_layout> ::= COMPACT + <size> + +<internal_layout> ::= <size> + <offset> + +<external_layout> ::= EXTERNAL { + <external_file>+ + } + +<virtual_layout> ::= <vmaps>*opt + +<vmaps> ::= MAPPING <int_value> { + <virtual_map> + <source_map> + } + +<virtual_map> ::= VIRTUAL { + <vmaps_selection> + } + +<source_map> ::= SOURCE { + FILE <file_name> + DATASET <dataset_name> + <vmaps_selection> + } + +<vmaps_selection> ::= <regular_hyperslab> | <irregular_hyperslab> | + <select_points> | <select_none> | <select_all> + +<regular_hyperslab> ::= SELECTION REGULAR_HYPERSLAB { + <start> + <stride> + <count> + <block> + } + +<irregular_hyperslab> ::= SELECTION IRREGULAR_HYPERSLAB { + <region_info>+ + } + +<select_points> ::= SELECTION POINT { + (<coor_list>)+ + } + +<select_none> ::= SELECTION NONE + +<select_all> ::= SELECTION ALL + +<dims> ::= (<dims_values>) + +<dims_values> ::= <int_value> | <int_value>, <dims_values> + +<external_file> ::= FILENAME <file_name> <size> <offset> + +<offset> ::= OFFSET <int_value> + +<size> ::= SIZE <int_value> + +<filter_ratio> ::= <size> | <compressionratio> + +<compressionratio> :: = <size> (<float_data>:1 COMPRESSION) + +<compression_filters> :: = FILTERS { + <filter_type>+ | NONE + } + +<filter_type> :: = <filter_deflate> | <filter_shuffle> | + <filter_flecther> | <filter_szip> | + <filter_nbit> | <filter_scaleoffset> | + <filter_default> + +<filter_default> :: = <filter_user> { + FILTER_ID <int_value> + <filter_comment>opt + <filter_params>opt + } + +<filter_user> :: = USER_DEFINED_FILTER + +<filter_deflate> :: = COMPRESSION DEFLATE { LEVEL <int_value> } + +<filter_shuffle> :: = PREPROCESSING SHUFFLE + +<filter_flecther> :: = CHECKSUM FLETCHER32 + +<filter_szip> :: = COMPRESSION SZIP { + PIXELS_PER_BLOCK <int_value> + <filter_szip_mode>opt + <filter_szip_coding>opt + <filter_szip_order>opt + <filter_szip_header>opt + } + +<filter_szip_mode> :: = MODE HARDWARE | K13 + +<filter_szip_coding> :: = CODING ENTROPY | NEAREST NEIGHBOUR + +<filter_szip_order> :: = BYTE_ORDER LSB | MSB + +<filter_szip_header> :: = HEADER RAW + +<filter_nbit> :: = CHECKSUM NBIT + +<filter_scaleoffset> :: = COMPRESSION SCALEOFFSET { MIN BITS <int_value> } + +<filter_comment> :: = COMMENT <identifier> + +<filter_params> :: = PARAMS { <int_value>* } + +<fillvalue> ::= FILLVALUE { + FILL_TIME H5D_FILL_TIME_ALLOC | H5D_FILL_TIME_NEVER | H5D_FILL_TIME_IFSET + VALUE H5D_FILL_VALUE_UNDEFINED | H5D_FILL_VALUE_DEFAULT | <any_element> + } + +<allocationtime> ::= ALLOCATION_TIME { + H5D_ALLOC_TIME_EARLY | H5D_ALLOC_TIME_INCR | + H5D_ALLOC_TIME_LATE + } + +<dataset_attribute> ::= <attribute> + +<softlink> ::= SOFTLINK <softlink_name> { + LINKTARGET <target> + } + +<softlink_name> ::= <identifier> + +<target> ::= <identifier> + +<external_link> ::= EXTERNAL_LINK <external_link_name> { + TARGETFILE <targetfile> + TARGETPATH <targetpath> <targetobj>opt + } + +<external_link_name> ::= <identifier> + +<user_defined_link> ::= USERDEFINED_LINK <external_link_name> { + LINKCLASS <user_link_type> + } + +<user_link_type> ::= <int_value> + +<targetfile> ::= <file_name> + +<targetpath> ::= <identifier> + +<targetobj> ::= <named_datatype> | <group> | <dataset> + +<identifier> ::= "a string" +// character '/' should be used with care. + +<pos_list> ::= <pos_int>, <pos_list> | <pos_int> + +<int_value> ::= 0 | <pos_int> + +<pos_int> ::= [1-9][0-9]* + +<hex_value> ::= 0x[0-F][0-F]+ | [0-F][0-F]+ +\endcode + +\section example110 An Example of an HDF5 File in DDL + +\code{.unparsed} +HDF5 "example.h5" { +GROUP "/" { + ATTRIBUTE "attr1" { + DATATYPE H5T_STRING { + STRSIZE 17; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SCALAR + DATA { + "string attribute" + } + } + DATASET "dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 10, 10 ) / ( 10, 10 ) } + DATA { + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + } + } + DATASET "dset2" { + DATATYPE H5T_COMPOUND { + H5T_STD_I32BE "a"; + H5T_IEEE_F32BE "b"; + H5T_IEEE_F64BE "c"; + } + DATASPACE SIMPLE { ( 5 ) / ( 5 ) } + DATA { + { + 1, + 0.1, + 0.01 + }, + { + 2, + 0.2, + 0.02 + }, + { + 3, + 0.3, + 0.03 + }, + { + 4, + 0.4, + 0.04 + }, + { + 5, + 0.5, + 0.05 + } + } + } + GROUP "group1" { + COMMENT "This is a comment for group1"; + DATASET "dset3" { + DATATYPE "/type1" + DATASPACE SIMPLE { ( 5 ) / ( 5 ) } + DATA { + { + [ 0, 1, 2, 3 ], + [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, + 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, + 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, + 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, + 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] + }, + { + [ 0, 1, 2, 3 ], + [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, + 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, + 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, + 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, + 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] + }, + { + [ 0, 1, 2, 3 ], + [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, + 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, + 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, + 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, + 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] + }, + { + [ 0, 1, 2, 3 ], + [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, + 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, + 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, + 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, + 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] + }, + { + [ 0, 1, 2, 3 ], + [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, + 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, + 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, + 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, + 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] + } + } + } + } + DATASET "dset3" { + DATATYPE H5T_VLEN { H5T_STD_I32LE } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0), (10, 11), (20, 21, 22), (30, 31, 32, 33) + } + } + GROUP "group2" { + HARDLINK "/group1" + } + SOFTLINK "slink1" { + LINKTARGET "somevalue" + } + DATATYPE "type1" H5T_COMPOUND { + H5T_ARRAY { [4] H5T_STD_I32BE } "a"; + H5T_ARRAY { [5][6] H5T_IEEE_F32BE } "b"; + } +} +} +\endcode + + */
\ No newline at end of file diff --git a/doxygen/dox/FileFormatSpec.dox b/doxygen/dox/FileFormatSpec.dox new file mode 100644 index 0000000..fc10574 --- /dev/null +++ b/doxygen/dox/FileFormatSpec.dox @@ -0,0 +1,23 @@ +/** \page FMT3 HDF5 File Format Specification Version 3.0 + +\htmlinclude H5.format.html + +*/ + +/** \page FMT2 HDF5 File Format Specification Version 2.0 + +\htmlinclude H5.format.2.0.html + +*/ + +/** \page FMT11 HDF5 File Format Specification Version 1.1 + +\htmlinclude H5.format.1.1.html + +*/ + +/** \page FMT1 HDF5 File Format Specification Version 1.0 + +\htmlinclude H5.format.1.0.html + +*/
\ No newline at end of file diff --git a/doxygen/dox/GettingStarted.dox b/doxygen/dox/GettingStarted.dox new file mode 100644 index 0000000..880491d --- /dev/null +++ b/doxygen/dox/GettingStarted.dox @@ -0,0 +1,3 @@ +/** \page GettingStarted \Code{Hello, HDF5!} + + */
\ No newline at end of file diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox new file mode 100644 index 0000000..9b9862b --- /dev/null +++ b/doxygen/dox/H5AC_cache_config_t.dox @@ -0,0 +1,415 @@ +/** + * \page H5AC-cache-config-t Metadata Cache Configuration + * \tableofcontents + * + * \section gcf General configuration fields + * + * \par version + * Integer field containing the version number of this version + * of the H5AC_cache_config_t structure. Any instance of + * H5AC_cache_config_t passed to the cache must have a known + * version number, or an error will be flagged. + * + * \par rpt_fcn_enabled + * \parblock + * Boolean field used to enable and disable the default + * reporting function. This function is invoked every time the + * automatic cache resize code is run, and reports on its activities. + * + * This is a debugging function, and should normally be turned off. + * \endparblock + * + * \par open_trace_file + * \parblock + * Boolean field indicating whether the trace_file_name + * field should be used to open a trace file for the cache. + * + * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead + * + * The trace file is a debuging feature that allow the capture of + * top level metadata cache requests for purposes of debugging and/or + * optimization. This field should normally be set to \c FALSE, as + * trace file collection imposes considerable overhead. + * + * This field should only be set to \c TRUE when the trace_file_name + * contains the full path of the desired trace file, and either + * there is no open trace file on the cache, or the \c close_trace_file + * field is also \c TRUE. + * \endparblock + * + * \par close_trace_file + * \parblock + * Boolean field indicating whether the current trace + * file (if any) should be closed. + * + * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead + * + * See the above comments on the open_trace_file field. This field + * should be set to \c FALSE unless there is an open trace file on the + * cache that you wish to close. + * \endparblock + * + * \par trace_file_name + * \parblock + * Full path of the trace file to be opened if the + * open_trace_file field is \c TRUE. + * + * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead + * + * In the parallel case, an ascii representation of the mpi rank of + * the process will be appended to the file name to yield a unique + * trace file name for each process. + * + * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN + * characters. + * \endparblock + * + * \par evictions_enabled + * \parblock + * Boolean field used to either report the current + * evictions enabled status of the cache, or to set the cache's + * evictions enabled status. + * + * In general, the metadata cache should always be allowed to + * evict entries. However, in some cases it is advantageous to + * disable evictions briefly, and thereby postpone metadata + * writes. However, this must be done with care, as the cache + * can grow quickly. If you do this, re-enable evictions as + * soon as possible and monitor cache size. + * + * At present, evictions can only be disabled if automatic + * cache resizing is also disabled (that is, \Code{(incr_mode == + * H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There + * is no logical reason why this should be so, but it simplifies + * implementation and testing, and I can't think of any reason + * why it would be desireable. If you can think of one, I'll + * revisit the issue. (JM) + * \endparblock + * + * \par set_initial_size + * Boolean flag indicating whether the size of the + * initial size of the cache is to be set to the value given in + * the initial_size field. If set_initial_size is \c FALSE, the + * initial_size field is ignored. + * + * \par initial_size + * If enabled, this field contain the size the cache is + * to be set to upon receipt of this structure. Needless to say, + * initial_size must lie in the closed interval \Code{[min_size, max_size]}. + * + * \par min_clean_fraction + * \c double in the range 0 to 1 indicating the fraction + * of the cache that is to be kept clean. This field is only used + * in parallel mode. Typical values are 0.1 to 0.5. + * + * \par max_size + * Maximum size to which the cache can be adjusted. The + * supplied value must fall in the closed interval + * \Code{[MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE]}. Also, \c max_size must + * be greater than or equal to \c min_size. + * + * \par min_size + * Minimum size to which the cache can be adjusted. The + * supplied value must fall in the closed interval + * \Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]}. Also, \c min_size + * must be less than or equal to \c max_size. + * + * \par epoch_length + * \parblock + * Number of accesses on the cache over which to collect + * hit rate stats before running the automatic cache resize code, + * if it is enabled. + * + * At the end of an epoch, we discard prior hit rate data and start + * collecting afresh. The epoch_length must lie in the closed + * interval \Code{[H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH]}. + * \endparblock + * + * + * \section csicf Cache size increase control fields + * + * \par incr_mode + * Instance of the \c H5C_cache_incr_mode enumerated type whose + * value indicates how we determine whether the cache size should be + * increased. At present there are two possible values: + * \li \c H5C_incr__off: Don't attempt to increase the size of the cache + * automatically.\n + * When this increment mode is selected, the remaining fields + * in the cache size increase section ar ignored. + * \li \c H5C_incr__threshold: Attempt to increase the size of the cache + * whenever the average hit rate over the last epoch drops + * below the value supplied in the \c lower_hr_threshold + * field.\n + * Note that this attempt will fail if the cache is already + * at its maximum size, or if the cache is not already using + * all available space. + * + * Note that you must set \c decr_mode to \c H5C_incr__off if you + * disable metadata cache entry evictions. + * + * \par lower_hr_threshold + * \parblock + * Lower hit rate threshold. If the increment mode + * (\c incr_mode) is \c H5C_incr__threshold and the hit rate drops below the + * value supplied in this field in an epoch, increment the cache size by + * \c size_increment. Note that cache size may not be incremented above + * \c max_size, and that the increment may be further restricted by the + * \c max_increment field if it is enabled. + * + * When enabled, this field must contain a value in the range [0.0, 1.0]. + * Depending on the \c incr_mode selected, it may also have to be less than + * \c upper_hr_threshold. + * \endparblock + * + * \par increment + * \parblock + * Double containing the multiplier used to derive the new + * cache size from the old if a cache size increment is triggered. + * The increment must be greater than 1.0, and should not exceed 2.0. + * + * The new cache size is obtained my multiplying the current max cache + * size by the increment, and then clamping to \c max_size and to stay + * within the \c max_increment as necessary. + * \endparblock + * + * \par apply_max_increment + * Boolean flag indicating whether the \c max_increment + * field should be used to limit the maximum cache size increment. + * + * \par max_increment + * If enabled by the \c apply_max_increment field described + * above, this field contains the maximum number of bytes by which the + * cache size can be increased in a single re-size. + * + * \par flash_incr_mode + * \parblock + * Instance of the \c H5C_cache_flash_incr_mode enumerated + * type whose value indicates whether and by which algorithm we should + * make flash increases in the size of the cache to accommodate insertion + * of large entries and large increases in the size of a single entry. + * + * The addition of the flash increment mode was occasioned by performance + * problems that appear when a local heap is increased to a size in excess + * of the current cache size. While the existing re-size code dealt with + * this eventually, performance was very bad for the remainder of the + * epoch. + * + * At present, there are two possible values for the \c flash_incr_mode: + * + * \li \c H5C_flash_incr__off: Don't perform flash increases in the size of the cache. + * + * \li \c H5C_flash_incr__add_space: Let \c x be either the size of a newly + * newly inserted entry, or the number of bytes by which the + * size of an existing entry has been increased.\n + * If \Code{x > flash_threshold * current max cache size}, + * increase the current maximum cache size by \Code{x * flash_multiple} + * less any free space in the cache, and star a new epoch. For + * now at least, pay no attention to the maximum increment. + * + * In both of the above cases, the flash increment pays no attention to + * the maximum increment (at least in this first incarnation), but DOES + * stay within max_size. + * + * With a little thought, it should be obvious that the above flash + * cache size increase algorithm is not sufficient for all circumstances + * -- for example, suppose the user round robins through + * \Code{(1/flash_threshold) +1} groups, adding one data set to each on each + * pass. Then all will increase in size at about the same time, requiring + * the max cache size to at least double to maintain acceptable + * performance, however the above flash increment algorithm will not be + * triggered. + * + * Hopefully, the add space algorithms detailed above will be sufficient + * for the performance problems encountered to date. However, we should + * expect to revisit the issue. + * \endparblock + * + * \par flash_multiple + * Double containing the multiple described above in the + * \c H5C_flash_incr__add_space section of the discussion of the + * \c flash_incr_mode section. This field is ignored unless \c flash_incr_mode + * is \c H5C_flash_incr__add_space. + * + * \par flash_threshold + * Double containing the factor by which current max cache + * size is multiplied to obtain the size threshold for the add_space flash + * increment algorithm. The field is ignored unless \c flash_incr_mode is + * \c H5C_flash_incr__add_space. + * + * + * \section csdcf Cache size decrease control fields + * + * \par decr_mode + * \parblock + * Instance of the \c H5C_cache_decr_mode enumerated type whose + * value indicates how we determine whether the cache size should be + * decreased. At present there are four possibilities. + * + * \li \c H5C_decr__off: Don't attempt to decrease the size of the cache + * automatically.\n + * When this increment mode is selected, the remaining fields + * in the cache size decrease section are ignored. + * \li \c H5C_decr__threshold: Attempt to decrease the size of the cache + * whenever the average hit rate over the last epoch rises + * above the value supplied in the \c upper_hr_threshold + * field. + * \li \c H5C_decr__age_out: At the end of each epoch, search the cache for + * entries that have not been accessed for at least the number + * of epochs specified in the epochs_before_eviction field, and + * evict these entries. Conceptually, the maximum cache size + * is then decreased to match the new actual cache size. However, + * this reduction may be modified by the \c min_size, the + * \c max_decrement, and/or the \c empty_reserve. + * \li \c H5C_decr__age_out_with_threshold: Same as age_out, but we only + * attempt to reduce the cache size when the hit rate observed + * over the last epoch exceeds the value provided in the + * \c upper_hr_threshold field. + * + * Note that you must set \c decr_mode to \c H5C_decr__off if you + * disable metadata cache entry evictions. + * \endparblock + * + * \par upper_hr_threshold + * \parblock + * Upper hit rate threshold. The use of this field + * varies according to the current \c decr_mode : + * + * \c H5C_decr__off or \c H5C_decr__age_out: The value of this field is + * ignored. + * + * \li \c H5C_decr__threshold: If the hit rate exceeds this threshold in any + * epoch, attempt to decrement the cache size by size_decrement.\n + * Note that cache size may not be decremented below \c min_size.\n + * Note also that if the \c upper_threshold is 1.0, the cache size\n + * will never be reduced. + * + * \li \c H5C_decr__age_out_with_threshold: If the hit rate exceeds this + * threshold in any epoch, attempt to reduce the cache size + * by evicting entries that have not been accessed for more + * than the specified number of epochs. + * \endparblock + * + * \par decrement + * \parblock + * This field is only used when the decr_mode is + * \c H5C_decr__threshold. + * + * The field is a double containing the multiplier used to derive the + * new cache size from the old if a cache size decrement is triggered. + * The decrement must be in the range 0.0 (in which case the cache will + * try to contract to its minimum size) to 1.0 (in which case the + * cache will never shrink). + * \endparblock + * + * \par apply_max_decrement + * Boolean flag used to determine whether decrements + * in cache size are to be limited by the \c max_decrement field. + * + * \par max_decrement + * Maximum number of bytes by which the cache size can be + * decreased in a single re-size. Note that decrements may also be + * restricted by the \c min_size of the cache, and (in age out modes) by + * the \c empty_reserve field. + * + * \par epochs_before_eviction + * \parblock + * Integer field used in \c H5C_decr__age_out and + * \c H5C_decr__age_out_with_threshold decrement modes. + * + * This field contains the number of epochs an entry must remain + * unaccessed before it is evicted in an attempt to reduce the + * cache size. If applicable, this field must lie in the range + * \Code{[1, H5C__MAX_EPOCH_MARKERS]}. + * \endparblock + * + * \par apply_empty_reserve + * Boolean field controlling whether the empty_reserve + * field is to be used in computing the new cache size when the + * decr_mode is H5C_decr__age_out or H5C_decr__age_out_with_threshold. + * + * \par empty_reserve + * \parblock + * To avoid a constant racheting down of cache size by small + * amounts in the \c H5C_decr__age_out and \c H5C_decr__age_out_with_threshold + * modes, this field allows one to require that any cache size + * reductions leave the specified fraction of unused space in the cache. + * + * The value of this field must be in the range [0.0, 1.0]. I would + * expect typical values to be in the range of 0.01 to 0.1. + * \endparblock + * + * + * \section pcf Parallel Configuration Fields + * + * In PHDF5, all operations that modify metadata must be executed collectively. + * + * We used to think that this was enough to ensure consistency across the + * metadata caches, but since we allow processes to read metadata individually, + * the order of dirty entries in the LRU list can vary across processes, + * which can result in inconsistencies between the caches. + * + * PHDF5 uses several strategies to prevent such inconsistencies in metadata, + * all of which use the fact that the same stream of dirty metadata is seen + * by all processes for purposes of synchronization. This is done by + * having each process count the number of bytes of dirty metadata generated, + * and then running a "sync point" whenever this count exceeds a user + * specified threshold (see \c dirty_bytes_threshold below). + * + * The current metadata write strategy is indicated by the + * \c metadata_write_strategy field. The possible values of this field, along + * with the associated metadata write strategies are discussed below. + * + * \par dirty_bytes_threshold + * \parblock + * Threshold of dirty byte creation used to + * synchronize updates between caches. (See above for outline and + * motivation.) + * + * This value MUST be consistent across all processes accessing the + * file. This field is ignored unless HDF5 has been compiled for + * parallel. + * \endparblock + * + * \par metadata_write_strategy + * Integer field containing a code indicating the + * desired metadata write strategy. The valid values of this field + * are enumerated and discussed below: + * + * \li #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY\n + * When metadata_write_strategy is set to this value, only process + * zero is allowed to write dirty metadata to disk. All other + * processes must retain dirty metadata until they are informed at + * a sync point that the dirty metadata in question has been written + * to disk.\n + * When the sync point is reached (or when there is a user generated + * flush), process zero flushes sufficient entries to bring it into + * complience with its min clean size (or flushes all dirty entries in + * the case of a user generated flush), broad casts the list of + * entries just cleaned to all the other processes, and then exits + * the sync point.\n + * Upon receipt of the broadcast, the other processes mark the indicated + * entries as clean, and leave the sync point as well. + * + * \li #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED\n + * In the distributed metadata write strategy, process zero still makes + * the decisions as to what entries should be flushed, but the actual + * flushes are distributed across the processes in the computation to + * the extent possible.\n + * In this strategy, when a sync point is triggered (either by dirty + * metadata creation or manual flush), all processes enter a barrier.\n + * On the other side of the barrier, process 0 constructs an ordered + * list of the entries to be flushed, and then broadcasts this list + * to the caches in all the processes.\n + * All processes then scan the list of entries to be flushed, flushing + * some, and marking the rest as clean. The algorithm for this purpose + * ensures that each entry in the list is flushed exactly once, and + * all are marked clean in each cache.\n + * Note that in the case of a flush of the cache, no message passing + * is necessary, as all processes have the same list of dirty entries, + * and all of these entries must be flushed. Thus in this case it is + * sufficient for each process to sort its list of dirty entries after + * leaving the initial barrier, and use this list as if it had been + * received from process zero.\n + * To avoid possible messages from the past/future, all caches must + * wait until all caches are done before leaving the sync point. + */
\ No newline at end of file diff --git a/doxygen/dox/H5Acreate.dox b/doxygen/dox/H5Acreate.dox new file mode 100644 index 0000000..18d648f --- /dev/null +++ b/doxygen/dox/H5Acreate.dox @@ -0,0 +1,9 @@ +/** + * \ingroup H5A + * \def H5Acreate() + * H5Acreate() is a macro that is mapped to either H5Acreate1() or + * H5Acreate2(). + * + * + * \todo Standardize the way we describe these macros! + */ diff --git a/doxygen/dox/H5Aiterate.dox b/doxygen/dox/H5Aiterate.dox new file mode 100644 index 0000000..46b9bb4 --- /dev/null +++ b/doxygen/dox/H5Aiterate.dox @@ -0,0 +1,9 @@ +/** + * \ingroup H5A + * \def H5Aiterate() + * H5Aiterate() is a macro that is mapped to either H5Aiterate1() or + * H5Aiterate2(). + * + * + * \todo Standardize the way we describe these macros! + */ diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox new file mode 100644 index 0000000..9ba0fab --- /dev/null +++ b/doxygen/dox/MetadataCachingInHDF5.dox @@ -0,0 +1,1020 @@ +/** \page TNMDC Metadata Caching in HDF5 + +\todo Revise this! + +\section intro Introduction + +In the 1.6.4 release, we introduced a re-implementation of the metadata +cache. That release contained an incomplete version of the cache which could not +be controlled via the API. The version in the 1.8 release is more mature and +includes new API calls that allow the user program to configure the metadata +cache both on file open and at run time. + +From the user perspective, the most striking effect of the new cache should be a +large reduction in the cache memory requirements when working with complex HDF5 +files. + +Those working with such files may also notice a reduction in file close time. + +Those working with HDF5 files with a simple structure shouldn't notice any +particular changes in most cases. In rare cases, there may be a significant +improvement in performance. + +The remainder of this document contains an architectural overview of the old and +new metadata caches, a discussion of algorithms used to automatically adjust +cache size to circumstances, and a high-level discussion of the cache +configuration controls. It can be safely skipped by anyone who works only with +HDF5 files with relatively simple structure (i.e. no huge groups, no datasets +with large numbers of chunks, and no objects with large numbers of attributes.) + +On the other hand, it is mandatory reading if you want to use something other +than the default metadata cache configuration. The documentation on the metadata +cache-related API calls will not make much sense without this background. + +\section oldnew Old and New Metadata Cache + +\subsection old The Old Metadata Cache + +The old metadata cache indexed the cache with a hash table with no provision for +collisions. Instead, collisions were handled by evicting the existing entry to +make room for the new entry. Aside from flushes, there was no other mechanism +for evicting entries, so the replacement policy could best be described as +"Evict on Collision". + +As a result, if two frequently used entries hashed to the same location, they +would evict each other regularly. To decrease the likelihood of this situation, +the default hash table size was set fairly large -- slightly more than +10,000. This worked well, but since the size of metadata entries is not bounded, +and since entries were only evicted on collision, the large hash table size +allowed the cache size to explode when working with HDF5 files with complex +structure. + +The "Evict on Collision" replacement policy also caused problems with the +parallel version of the HDF5 library, as a collision with a dirty entry could +force a write in response to a metadata read. Since all metadata writes must be +collective in the parallel case while reads need not be, this could cause the +library to hang if only some of the processes participated in a metadata read +that forced a write. Prior to the implementation of the new metadata cache, we +dealt with this issue by maintaining a shadow cache for dirty entries evicted by +a read. + +\subsection new The New Metadata Cache + +The new metadata cache was designed to address the above issues. After +implementation, it became evident that the working set size for HDF5 files +varies widely depending on both structure and access patterns. Thus it was +necessary to add support for cache size adjustment under either automatic or +user program control (see section 2.3 for details). + +When the cache is operating under direct user program control, it is also +possible to temporarily disable evictions from the metadata cache so as to +maximize raw data throughput at the expense of allowing the cache to grow +without bound until evictions are enabled again. + +Structurally, the new metadata cache can be thought of as a heavily modified +version of the UNIX buffer cache as described in chapter three of M. J. Bach's +"The Design of the UNIX Operating System" In essence, the UNIX buffer cache uses +a hash table with chaining to index a pool of fixed-size buffers. It uses the +LRU replacement policy to select candidates for eviction. + +Since HDF5 metadata entries are not of fixed size and may grow arbitrarily +large, the size of the new metadata cache cannot be controlled by setting a +maximum number of entries. Instead, the new cache keeps a running sum of the +sizes of all entries and attempts to evict entries as necessary to stay within a +user-specified maximum size. (Note the use of the word "attempts" here -- as +will be seen, it is possible for the cache to exceed its currently specified +maximum size.) At present, the LRU replacement policy is the only option for +selecting candidates for eviction. + +Per the standard Unix buffer cache, dirty entries are given two passes through +the LRU list before being evicted. The first time they reach the end of the LRU +list, they are flushed, marked as clean, and moved to the head of the LRU +list. When a clean entry reaches the end of the LRU list, it is simply evicted +if space is needed. + +The cache cannot evict entries that are locked, and thus it will temporarily +grow beyond its maximum size if there are insufficient unlocked entries +available for eviction. + +In the parallel version of the library, only the cache running under process 0 +of the file communicator is allowed to write metadata to file. All the other +caches must retain dirty metadata until the process 0 cache tells them that the +metadata is clean. + +Since all operations modifying metadata must be collective, all caches see the +same stream of dirty metadata. This fact is used to allow them to synchronize +every n bytes of dirty metadata, where n is a user-configurable value that +defaults to 256 KB. + +To avoid sending the other caches messages from the future, process 0 must not +write any dirty entries until it reaches a synchronization point. When it +reaches a synchronization point, it writes entries as needed, and then +broadcasts the list of flushed entries to the other caches. The caches on the +other processes use this list to mark entries clean before they leave the +synchronization point, allowing them to evict those entries as needed. + +The caches will also synchronize on a user-initiated flush. + +To minimize overhead when running in parallel, the cache maintains a "clean" LRU +list in addition to the regular LRU list. This list contains only clean entries +and is used as a source of candidates for eviction when flushing dirty entries +is not allowed. + +Since flushing entries is forbidden most of the time when running in parallel, +the caches can be forced to exceed their maximum sizes if they run out of clean +entries to evict. + +To decrease the likelihood of this event, the new cache allows the user to +specify a minimum clean size -- which is a minimum total size of all the entries +on the clean LRU plus all unused space in the cache. + +While the clean LRU list is only maintained in the parallel version of the HDF5 +library, the notion of a minimum clean size still applies in the serial +case. Here it is used to force a mix of clean and dirty entries in the cache +even in the write-only case. + +This, in turn, reduces the number of redundant flushes by avoiding the case in +which the cache fills with dirty metadata and all entries must be flushed before +a clean entry can be evicted to make room for a new entry. + +Observe that in both the serial and parallel cases, the maintenance of a minimum +clean size modifies the replacement policy, as dirty entries may be flushed +earlier than would otherwise be the case so as to maintain the desired amount of +clean and/or empty space in the cache. + +While the new metadata cache only supports the LRU replacement policy at +present, that may change. Support for multiple replacement policies was very +much in mind when the cache was designed, as was the ability to switch +replacement policies at run time. The situation has been complicated by the +later addition of the adaptive cache resizing requirement, as two of the +resizing algorithms piggyback on the LRU list. However, if there is a need for +additional replacement policies, it shouldn't be too hard to implement them. + +\section adapt Adaptive Cache Resizing in the New Metadata Cache + +As mentioned earlier, the metadata working set size for an HDF5 file varies +wildly depending on the structure of the file and the access pattern. For +example, a 2MB limit on metadata cache size is excessive for an H5repack of +almost all HDF5 files we have tested. However, I have a file submitted by one of +our users that will run a 13% hit rate with this cache size and will lock up one +of our Linux boxes using the old metadata cache. Increase the new metadata cache +size to 4 MB, and the hit rate exceeds 99%. + +In this case, the main culprit is a root group with more than 20,000 entries in +it. As a result, the root group heap exceeds 1 MB, which tends to crowd out the +rest of the metadata in a 2 MB cache + +This case and a number of synthetic tests convinced us that we needed to modify +the new metadata cache to expand and contract according to need within +user-specified bounds. + +I was unable to find any previous work on this problem, so I invented solutions +as I went along. If you are aware of prior work, please send me references. The +closest I was able to come was a group of embedded CPU designers who were +turning off sections of their cache to conserve power. + +\subsection increasing Increasing the Cache Size + +In the context of the HDF5 library, the problem of increasing the cache size as +necessary to contain the current working set turns out to involve two rather +different issues. + +The first of these, which was recognized immediately, is the problem of +recognizing long term changes in working set size, and increasing the cache size +accordingly, while not reacting to transients. + +The second, which I recognized the hard way, is to adjust the cache size for +sudden, dramatic increases in working set size caused by requests for large +pieces of metadata which may be larger than the current metadata cache size. + +The algorithms for handling these situations are discussed below. These problems +are largely orthogonal to each other, so both algorithms may be used +simultaneously. + +\subsubsection hrtcsi Hit Rate Threshold Cache Size Increment + +Perhaps the most obvious heuristic for identifying cases in which the cache is +too small involves monitoring the hit rate. If the hit rate is low for a while, +and the cache is at its current maximum size, the current maximum cache size is +probably too small. + +The hit rate threshold algorithm for increasing cache size applies this +intuition directly. + +Hit rate statistics are collected over a user-specified number of cache +accesses. This period is known as an epoch. + +At the end of each epoch, the hit rate is computed, and the counters are +reset. If the hit rate is below a user-specified threshold and the cache is at +its current maximum size, the maximum size of the cache is increased by a +user-specified multiple. If required, the new cache maximum size is clipped to +stay within the user-specified upper bound on the maximum cache size, and +optionally, within a user-specified maximum increment. + +My tests indicate that this algorithm works well in most cases. However, in a +synthetic test in which hit rate increased slowly with cache size, and load +remained steady for many epochs, I observed a case in which cache size increased +until the hit rate just exceeded the specified minimum and then stalled. This is +a problem, as to avoid volatility, it is necessary to set the minimum hit rate +threshold well below the desired hit rate. Thus we may find ourselves with a +cache running with a 91% hit rate when we really want it to increase its size +until the hit rate is about 99%. + +If this case occurs frequently in actual use, I will have to come up with an +improved algorithm. Please let me know if you see this behavior. However, I had +to work rather hard to create it in my synthetic tests, so I would expect it to +be uncommon. + +\subsubsection fcsi Flash Cache Size Increment + +A fundamental problem with the above algorithm is that contains the hidden +assumption that cache entries are relatively small in comparison to the cache +itself. While I knew this assumption was not generally true when I developed the +algorithm, I thought that cases, where it failed, would be so rare as to not be +worth considering, as even if they did occur, the above algorithm would rectify +the situation within an epoch or two. + +While it is true that such occurrences are rare, and it is true that the hit +rate threshold cache size increment algorithm will rectify the situation +eventually, the performance degradation experienced by users while waiting for +the epoch to end was so extreme that some way of accelerating response to such +situations was essential. + +To understand the problem, consider the following use case: + +Suppose we create a group, and then repeatedly create a new data set in the +group, write some data to it and then close it. + +In some versions of the HDF5 file format, the names of the datasets will be +stored in a local heap associated with the group, and the space for that heap +will be allocated in a single, contiguous chunk. When this local heap is full, +we allocate a new chunk twice the size of the old, copy the data from the old +local heap into the new, and discard the old local heap. + +By default, the minimum metadata cache size is set to 2 MB. Thus in this use +case, our hit rate will be fine as long as the local heap is no larger than a +little less than 2 MB, as the group related metadata is accessed frequently and +never evicted, and the data set related metadata is never accessed once the data +set is closed, and thus is evicted smoothly to make room for new data sets. + +All this changes abruptly when the local heap finally doubles in size to a value +above the slightly less than 2 MB limit. All of a sudden, the local heap is the +size of the metadata cache, and the cache must constantly swap it in to access +it, and then swap it out to make room for other metadata. + +The hit rate threshold-based algorithm for increasing the cache size will fix +this problem eventually, but performance will be very bad until it does, as the +metadata cache will largely ineffective until its size is increased. + +An obvious heuristic for addressing this "big rock in a small pond" issue is to +watch for large "incoming rocks", and increase the size of the "pond" if the +rock is so big that it will force most of the "water" out of the "pond". + +The add space flash cache size increment algorithm applies this intuition +directly: + +Let x be either the size of a newly inserted entry, a newly loaded entry, or the +number of bytes by which the size of an existing entry has been increased +(i.e. the size of the "rock"). + +If x is greater than some user-specified fraction of the current maximum cache +size, increase the current maximum cache size by x times some user-specified +multiple, less any free space that was in the cache, to begin with. Further, to +avoid confusing the other cache size increment/decrement code, start a new +epoch. + +At present, this algorithm pays no attention to any user-specified limit on the +maximum size of any single cache size increase, but it DOES stay within the +user-specified upper bound on the maximum cache size. + +While it should be easy to see how this algorithm could be fooled into +inactivity by a large number of entries that were not quite large enough to +cross the threshold, in practice it seems to work reasonably well. + +Needless to say, I will revisit the issue should this cease to be the case. + +\subsection decreasing Decreasing the Cache Size + +Identifying cases in which the maximum cache size is larger than necessary +turned out to be more difficult. + +\subsubsection hrtcsr Hit Rate Threshold Cache Size Reduction + +One obvious heuristic is to monitor the hit rate and guess that we can safely +decrease cache size if the hit rate exceeds some user-supplied threshold (say +.99995). The hit rate threshold size decrement algorithm implemented in the new +metadata cache implements this intuition as follows: + +At the end of each epoch (this is the same epoch that is used in the cache size +increment algorithm), the hit rate is compared with the user-specified +threshold. If the hit rate exceeds that threshold, the current maximum cache +size is decreased by a user-specified factor. If required, the size of the +reduction is clipped to stay within a user-specified lower bound on the maximum +cache size, and optionally, within a user-specified maximum decrement. + +In my synthetic tests, this algorithm works poorly. Even with a very high +threshold and a small maximum reduction, it results in cache size +oscillations. The size increment code typically increments the maximum cache +size above the working set size. This results in a high hit rate, which causes +the threshold size decrement code to reduce the maximum cache size below the +working set size, which causes the hit rate to crash causing the cycle to +repeat. The resulting average hit rate is poor. + +It remains to be seen if this behavior will be seen in the field. The algorithm +is available for use, but it wouldn't be my first choice. If you use it, please +report back. + +\subsubsection acsr Ageout Cache Size Reduction + +Another heuristic for dealing with oversized cache conditions is to look for +entries that haven't been accessed for a long time, evict them, and reduce the +cache size accordingly. + +The age out cache size reduction applies this intuition as follows: At the end +of each epoch (again the same epoch as used in the cache size increment +algorithm), all entries that haven't been accessed for a user-configurable +number of epochs (1 - 10 at present) are evicted. The maximum cache size is then +reduced to equal the sum of the sizes of the remaining entries. The size of the +reduction is clipped to stay within a user-specified lower bound on maximum +cache size, and optionally, within a user-specified maximum decrement. + +In addition, the user may specify a minimum fraction of the cache which must be +empty before the cache size is reduced. Thus if an empty reserve of 0.1 was +specified on a 10 MB cache, there would be no cache size reduction unless the +eviction of aged out entries resulted in more than 1 MB of empty space. Further, +even after the reduction, the cache would be one-tenth empty. + +In my synthetic tests, the age out algorithm works rather well, although it is +somewhat sensitive to the epoch length and age out period selection. + +\subsubsection awhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction + +To address these issues, I combined the hit rate threshold and age out +heuristics. + +Age out with threshold works just like age out, except that the algorithm is not +run unless the hit rate exceeded a user-specified threshold in the previous +epoch. + +In my synthetic tests, age out with threshold seems to work nicely, with no +observed oscillation. Thus I have selected it as the default cache size +reduction algorithm. + +For those interested in such things, the age out algorithm is implemented by +inserting a marker entry at the head of the LRU list at the beginning of each +epoch. Entries that haven't been accessed for at least n epochs are simply +entries that appear in the LRU list after the n-th marker at the end of an +epoch. + +\section configuring Configuring the New Metadata Cache + +Due to a lack of resources, the design work on the automatic cache size +adjustment algorithms was done hastily, using primarily synthetic tests. I don't +think I spent more than a couple weeks writing and running performance tests -- +most time went into coding and functional testing. + +As a result, while I think the algorithms provided for adaptive cache resizing +will work well in actual use, I don't really know (although preliminary results +from the field are promising). Fortunately, the issue shouldn't arise for the +vast majority of HDF5 users, and those for whom it may arise should be savvy +enough to recognize problems and deal with them. + +For this latter class of users, I have implemented a number of new API calls +allowing the user to select and configure the cache resize algorithms, or to +turn them off and control cache size directly from the user program. There are +also API calls that allow the user program to monitor hit rate and cache size. + +From the user perspective, all the cache configuration data for a given file is +contained in an instance of the \ref H5AC_cache_config_t structure -- the definition +of which is given below: + +\snippet H5ACpublic.h H5AC_cache_config_t_snip + +This structure is defined in \c H5ACpublic.h. Each field is discussed below and in +the associated header comment. + +The C API allows you to get and set this structure directly. Unfortunately, the +Fortran API has to do this with individual parameters for each of the fields +(with the exception of version). + +While the API calls are discussed individually in the reference manual, the +following high-level discussion of what fields to change for different purposes +should be useful. + +\subsection gconfig General Configuration + +The \c version field is intended to allow \THG to change the \c +H5AC_cache_config_t structure without breaking old code. For now, this field +should always be set to \c H5AC__CURR_CACHE_CONFIG_VERSION, even when you are +getting the current configuration data from the cache. The library needs the +version number to know where fields are located with reference to the supplied +base address. + +The \ref H5AC_cache_config_t.rpt_fcn_enabled "rpt_fcn_enabled" field is a +boolean flag that allows you to turn on and off the resize reporting function +that reports the activities of the adaptive cache resize code at the end of each +epoch -- assuming that it is enabled. + +The report function is unsupported, so you are on your own if you use it. Since +it dumps status data to stdout, you should not attempt to use it with Windows +unless you modify the source. You may find it useful if you want to experiment +with different adaptive resize configurations. It is also a convenient way of +diagnosing poor cache configuration. Finally, if you do lots of runs with +identical behavior, you can use it to determine the metadata cache size needed +in each phase of your program so you can set the required cache sizes manually. + +The trace file fields are also unsupported. They allow one to open and close a +trace file in which all calls to the metadata cache are logged in a +user-specified file for later analysis. The feature is intended primarily for +THG use in debugging or optimizing the metadata cache in cases where users in +the field observe obscure failures or poor performance that we cannot re-create +in the lab. The trace file will allow us to re-create the exact sequence of +cache operations that are triggering the problem. + +At present we do not have a playback utility for trace files, although I imagine +that we will write one quickly when and if we need it. + +To enable the trace file, you load the full path of the desired trace file into +\ref H5AC_cache_config_t.trace_file_name "trace_file_name", and set \ref +H5AC_cache_config_t.open_trace_file "open_trace_file" to \c TRUE. In the +parallel case, an ASCII representation of the rank of each process is appended +to the supplied trace file name to create a unique trace file name for that +process. + +To close an open trace file, set \ref H5AC_cache_config_t.close_trace_file +"close_trace_file" to \c TRUE. + +It must be emphasized that you are on your own if you play with the trace file +feature absent a request from \THG. Needless to say, the trace file feature is +disabled by default. If you enable it, you will take a large performance hit and +generate huge trace files. + +The \ref H5AC_cache_config_t.evictions_enabled "evictions_enabled" field is a +boolean flag allowing the user to disable the eviction of entries from the +metadata cache. Under normal operation conditions, this field will always be set +to \c TRUE. + +In rare circumstances, the raw data throughput requirements may be so high that +the user wishes to postpone metadata writes so as to reserve I/O throughput for +raw data. The \ref H5AC_cache_config_t.evictions_enabled "evictions_enabled" +field exists to allow this -- although the user is to be warned that the +metadata cache will grow without bound while evictions are disabled. Thus +evictions should be re-enabled as soon as possible, and it may be wise to +monitor cache size and statistics (to see how to enable statistics, see the +debugging facilities section below). + +Evictions may only be disabled when the automatic cache resize code is disabled +as well. Thus to disable evictions, not only must the user set the \ref +H5AC_cache_config_t.evictions_enabled "evictions_enabled" field to \c FALSE, but +he must also set \ref H5AC_cache_config_t.incr_mode "incr_mode" to +#H5C_incr__off, set \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode" +to #H5C_flash_incr__off, and set \ref H5AC_cache_config_t.decr_mode "decr_mode" +to #H5C_decr__off. + +To re-enable evictions, just set \ref H5AC_cache_config_t.evictions_enabled +"evictions_enabled" back to \c TRUE. + +Before passing on to other subjects, it is worth re-iterating that disabling +evictions is an extreme step. Before attempting it, you might consider setting a +large cache size manually, and flushing the cache just before high raw data +throughput is required. This may yield the desired results without the risks +inherent in disabling evictions. + +The \ref H5AC_cache_config_t.set_initial_size "set_initial_size" and \ref +H5AC_cache_config_t.initial_size "initial_size" fields allow you to specify an +initial maximum cache size. If \ref H5AC_cache_config_t.set_initial_size +"set_initial_size" is \c TRUE, \ref H5AC_cache_config_t.initial_size +"initial_size" must lie in the interval [\ref H5AC_cache_config_t.min_size +"min_size", \ref H5AC_cache_config_t.max_size "max_size"] (see below for a +discussion of the \ref H5AC_cache_config_t.min_size "min_size" and \ref +H5AC_cache_config_t.max_size "max_size" fields). + +If you disable the adaptive cache resizing code (done by setting \ref +H5AC_cache_config_t.incr_mode "incr_mode" to #H5C_incr__off, \ref +H5AC_cache_config_t.flash_incr_mode "flash_incr_mode" to #H5C_flash_incr__off, +and \ref H5AC_cache_config_t.decr_mode "decr_mode" to #H5C_decr__off), you can +use these fields to control maximum cache size manually, as the maximum cache +size will remain at the initial size. + +Note, that the maximum cache size is only modified when \ref +H5AC_cache_config_t.set_initial_size "set_initial_size" is \c TRUE. This allows +the use of configurations specified at compile time to change resize +configuration without altering the current maximum size of the cache. Without +this feature, an additional call would be required to get the current maximum +cache size so as to set the \ref H5AC_cache_config_t.initial_size "initial_size" +to the current maximum cache size, and thereby avoid changing it. + +The \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" sets the +current minimum clean size as a fraction of the current max cache size. While +this field was originally used only in the parallel version of the library, it +now applies to the serial version as well. Its value must lie in the range +\Code{[0.0, 1.0]}. 0.01 is reasonable in the serial case, and 0.3 in the +parallel. + +A potential interaction, discovered at release 1.8.3, between the enforcement of +the \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" and the +adaptive cache resize code can severely degrade performance. While this +interaction is easily dealt with in the serial case by setting \ref +H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" to 0.01, the problem +is more difficult in the parallel case. Please see the Interactions section +below for further details. + +The \ref H5AC_cache_config_t.max_size "max_size" and \ref +H5AC_cache_config_t.min_size "min_size" fields specify the range of maximum +sizes that may be set for the cache by the automatic resize code. \ref +H5AC_cache_config_t.min_size "min_size" must be less than or equal to +\ref H5AC_cache_config_t.max_size "max_size", and both must lie in the range +\Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]} -- currently [1 KB, +128 MB]. If you routinely run a cache size in the top half of this range, you +should increase the hash table size. To do this, modify the \c +H5C__HASH_TABLE_LEN \Code{\#define} in \c H5Cpkg.h and re-compile. At present, +\c H5C__HASH_TABLE_LEN must be a power of two. + +The \c epoch_length is the number of cache accesses between runs of the adaptive +cache size control algorithms. It is ignored if these algorithms are turned +off. It must lie in the range \Code{[H5C__MIN_AR_EPOCH_LENGTH, +H5C__MAX_AR_EPOCH_LENGTH]} -- currently [100, 1000000]. The above constants are +defined in \c H5Cprivate.h. 50000 is a reasonable value. + +\subsection increment Increment Configuration + +The \ref H5AC_cache_config_t.incr_mode "incr_mode" field specifies the cache +size increment algorithm used. Its value must be a member of the \ref +H5C_cache_incr_mode enum type -- currently either #H5C_incr__off or +#H5C_incr__threshold (note the double underscores after \c "incr"). This type is +defined in H5Cpublic.h. + +If \ref H5AC_cache_config_t.incr_mode "incr_mode" is set to #H5C_incr__off, +regular automatic cache size increases are disabled, and the \ref +H5AC_cache_config_t.lower_hr_threshold "lower_hr_threshold", \ref +H5AC_cache_config_t.increment "increment", \ref +H5AC_cache_config_t.apply_max_increment "apply_max_increment", and \ref +H5AC_cache_config_t.max_increment "max_increment", fields are ignored. + +The \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode" field specifies +the flash cache size increment algorithm used. Its value must be a member of the +\ref H5C_cache_flash_incr_mode enum type -- currently either +#H5C_flash_incr__off or #H5C_flash_incr__add_space (note the double underscores +after \c "incr"). This type is defined in H5Cpublic.h. + +If \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode" is set to +#H5C_flash_incr__off, flash cache size increases are disabled, and the \ref +H5AC_cache_config_t.flash_multiple "flash_multiple", and \ref +H5AC_cache_config_t.flash_threshold "flash_threshold", fields are ignored. + +\subsubsection hrtcsic Hit Rate Threshold Cache Size Increase Configuration + +If \ref H5AC_cache_config_t.incr_mode "incr_mode" is #H5C_incr__threshold, the +cache size is increased via the hit rate threshold algorithm. The remaining +fields in the section are then used as follows: + +\ref H5AC_cache_config_t.lower_hr_threshold "lower_hr_threshold" is the +threshold below which the hit rate must fall to trigger an increase. The value +must lie in the range \Code{[0.0 - 1.0]}. In my tests, a relatively high value +seems to work best -- 0.9 for example. + +\ref H5AC_cache_config_t.increment "increment" is the factor by which the old +maximum cache size is multiplied to obtain an initial new maximum cache size +when an increment is needed. The actual change in size may be smaller as +required by \ref H5AC_cache_config_t.max_size "max_size" (above) and \c +max_increment (discussed below). increment must be greater than or equal to +1.0. If you set it to 1.0, you will effectively turn off the increment code. 2.0 +is a reasonable value. + +\ref H5AC_cache_config_t.apply_max_increment "apply_max_increment" and \ref +H5AC_cache_config_t.max_increment "max_increment" allow the user to specify a +maximum increment. If \ref H5AC_cache_config_t.apply_max_increment +"apply_max_increment" is \c TRUE, the cache size will never be increased by more +than the number of bytes specified in \ref H5AC_cache_config_t.max_increment +"max_increment" in any single increase. + +\subsubsection fcsic Flash Cache Size Increase Configuration + +If \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode" is set to +#H5C_flash_incr__add_space, flash cache size increases are enabled. The size of +the cache will be increased under the following circumstances: + +Let \c t be the current maximum cache size times the value of the \ref +H5AC_cache_config_t.flash_threshold "flash_threshold" field. + +Let \c x be either the size of the newly inserted entry, the size of the newly +loaded entry, or the number of bytes added to the size of the entry under +consideration for triggering a flash cache size increase. + +If \Code{t < x}, the basic condition for a flash cache size increase is met, and +we proceed as follows: + +Let \c space_needed equal \c x less the amount of free space in the cache. + +Further, let \ref H5AC_cache_config_t.increment "increment" equal \c +space_needed times the value of the \ref H5AC_cache_config_t.flash_multiple +"flash_multiple" field. If \ref H5AC_cache_config_t.increment "increment" plus +the current cache size is greater than \ref H5AC_cache_config_t.max_size +"max_size" (discussed above), reduce \ref H5AC_cache_config_t.increment +"increment" so that \ref H5AC_cache_config_t.increment "increment" plus the +current cache size is equal to \ref H5AC_cache_config_t.max_size "max_size". + +If the increment is greater than zero, increase the current cache size by \ref +H5AC_cache_config_t.increment "increment". To avoid confusing the other cache +size increment or decrement algorithms, start a new epoch. Note, however, that +we do not cycle the epoch markers if some variant of the age out algorithm is in +use. + +The use of the \ref H5AC_cache_config_t.flash_threshold "flash_threshold" field +is discussed above. It must be a floating-point value in the range of +\Code{[0.1, 1.0]}. 0.25 is a reasonable value. + +The use of the \ref H5AC_cache_config_t.flash_multiple "flash_multiple" field is +also discussed above. It must be a floating-point value in the range of +\Code{[0.1, 10.0]}. 1.4 is a reasonable value. + +\subsection decrement Decrement Configuration + +The \ref H5AC_cache_config_t.decr_mode "decr_mode" field specifies the cache +size decrement algorithm used. Its value must be a member of the \ref +H5C_cache_decr_mode enum type -- currently either #H5C_decr__off, +#H5C_decr__threshold, #H5C_decr__age_out, or #H5C_decr__age_out_with_threshold +(note the double underscores after \c "decr"). This type is defined in +H5Cpublic.h. + +If \ref H5AC_cache_config_t.decr_mode "decr_mode" is set to #H5C_decr__off, +automatic cache size decreases are disabled, and the remaining fields in the +cache size decrease control section are ignored. + +\subsubsection hrtcsdc Hit Rate Threshold Cache Size Decrease Configuration + +If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__threshold, the +cache size is decreased by the threshold algorithm, and the remaining fields of +the decrement section are used as follows: + +\ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" is the +threshold above which the hit rate must rise to trigger cache size reduction. It +must be in the range \Code{[0.0, 1.0]}. In my synthetic tests, very high values +like .9995 or .99995 seemed to work best. + +\ref H5AC_cache_config_t.decrement "decrement" is the factor by which the +current maximum cache size is multiplied to obtain a tentative new maximum cache +size. It must lie in the range \Code{[0.0, 1.0]}. Relatively large values like +.9 seem to work best in my synthetic tests. Note that the actual size reduction +may be smaller as required by \ref H5AC_cache_config_t.min_size "min_size" and +\ref H5AC_cache_config_t.max_decrement "max_decrement" (discussed below). \ref +H5AC_cache_config_t.apply_max_decrement "apply_max_decrement" and \ref +H5AC_cache_config_t.max_decrement "max_decrement" allow the user to specify a +maximum decrement. If \ref H5AC_cache_config_t.apply_max_decrement +"apply_max_decrement" is \c TRUE, the cache size will never be reduced by more +than \ref H5AC_cache_config_t.max_decrement "max_decrement" bytes in any single +reduction. + +With the hit rate threshold cache size decrement algorithm, the remaining fields +in the section are ignored. + +\subsubsection acsr Ageout Cache Size Reduction + +If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out the +cache size is decreased by the ageout algorithm, and the remaining fields of the +decrement section are used as follows: + +\ref H5AC_cache_config_t.epochs_before_eviction "epochs_before_eviction" is the +number of epochs an entry must reside unaccessed in the cache before it is +evicted. This value must lie in the range \Code{[1, H5C__MAX_EPOCH_MARKERS]}. \c +H5C__MAX_EPOCH_MARKERS is defined in H5Cprivate.h, and is currently set to 10. + +\ref H5AC_cache_config_t.apply_max_decrement "apply_max_decrement" and \ref +H5AC_cache_config_t.max_decrement "max_decrement" are used as in section +2.4.3.1. + +\ref H5AC_cache_config_t.apply_empty_reserve "apply_emty_reserve" and \ref +H5AC_cache_config_t.empty_reserve "empty_reserve" allow the user to specify a +minimum empty reserve as discussed in section 2.3.2.2. An empty reserve of 0.05 +or 0.1 seems to work well. + +The \ref H5AC_cache_config_t.decrement "decrement" and \ref +H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" fields are ignored +in this case. + +\subsubsection awhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction + +If \ref H5AC_cache_config_t.decr_mode "decr_mode" is +#H5C_decr__age_out_with_threshold, the cache size is decreased by the ageout +with hit rate threshold algorithm, and the fields of decrement section are used +as per the Ageout algorithm (see 5.3.2) with the exception of \ref +H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold". + +Here, \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" is the +threshold above which the hit rate must rise to trigger cache size reduction. It +must be in the range \Code{[0.0, 1.0]}. In my synthetic tests, high values like +.999 seemed to work well. + +\subsection parallel Parallel Configuration + +This section is a catch-all for parallel specific configuration data. At +present, it has only one field -- +\ref H5AC_cache_config_t.dirty_bytes_threshold "dirty_bytes_threshold". + +In PHDF5, all operations that modify metadata must be executed collectively. We +used to think that this was enough to ensure consistency across the metadata +caches, but since we allow processes to read metadata individually, the order of +dirty entries in the LRU list can vary across processes. This, in turn, can +change the order in which dirty metadata cache entries reach the bottom of the +LRU and are flushed to disk -- opening the door to messages from the past and +messages from the future bugs. + +To prevent this, only the metadata cache on process 0 of the file communicator +is allowed to write to file, and then only after entering a sync point with the +other caches. After it writes entries to file, it sends the base addresses of +the now clean entries to the other caches, so they can mark these entries clean +as well, and then leaves the sync point. The other caches mark the specified +entries as clean before they leave the synch point as well. (Observe, that since +all caches see the same stream of dirty metadata, they will all have the same +set of dirty entries upon sync point entry and exit.) + +The different caches know when to synchronize by counting the number of bytes of +dirty metadata created by the collective operations modifying metadata. Whenever +this count exceeds the value specified in the \ref +H5AC_cache_config_t.dirty_bytes_threshold "dirty_bytes_threshold", they all +enter the sync point, and process 0 flushes down to its minimum clean size and +sends the list of newly cleaned entries to the other caches. + +Needless to say, the value of the \ref H5AC_cache_config_t.dirty_bytes_threshold +"dirty_bytes_threshold" field must be consistent across all the caches operating +on a given file. + +All dirty metadata can also by flushed under programmatic control via the +H5Fflush() call. This call must be collective and will reset the dirty data +counts on each metadata cache. + +Absent calls to H5Fflush(), dirty metadata will only be flushed when the \ref +H5AC_cache_config_t.dirty_bytes_threshold "dirty_bytes_threshold" is exceeded, +and then only down to the H5AC_cache_config_t.min_clean_fraction +"min_clean_fraction". Thus, if a program does all its metadata modifications in +one phase, and then doesn't modify metadata thereafter, a residue of dirty +metadata will be frozen in the metadata caches for the remainder of the +computation -- effectively reducing the sizes of the caches. + +In the default configuration, the caches will eventually resize themselves to +maintain an acceptable hit rate. However, this will take time, and it will +increase the application's footprint in memory. + +If your application behaves in this manner, you can avoid this by a collective +call to H5Fflush() immediately after the metadata modification phase. + +\subsection interactions Interactions + +Evictions may not be disabled unless the automatic cache resize code is disabled +as well (by setting \ref H5AC_cache_config_t.decr_mode "decr_mode" to +#H5C_decr__off, \c flash_decr_mode to #H5C_flash_incr__add_space, and \ref +H5AC_cache_config_t.incr_mode "incr_mode" to #H5C_incr__off) -- thus placing the +cache size under the direct control of the user program. + +There is no logical necessity for this restriction. It is imposed because it +simplifies testing greatly and because I can't see any reason why one would want +to disable evictions while the automatic cache size adjustment code was +enabled. This restriction can be relaxed if anyone can come up with a good +reason to do so. + +At present, there are two interactions between the increment and decrement +sections of the configuration. + +If \ref H5AC_cache_config_t.incr_mode "incr_mode" is #H5C_incr__threshold, and +\ref H5AC_cache_config_t.decr_mode "decr_mode" is either #H5C_decr__threshold or +#H5C_decr__age_out_with_threshold, then \ref +H5AC_cache_config_t.lower_hr_threshold "lower_hr_threshold" must be strictly +less than \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold". + +Also, if the flash cache size increment code is enabled and is triggered, it +will restart the current epoch without calling any other cache size increment or +decrement code. + +In both the serial and parallel cases, there is the potential for an interaction +between the \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" and +the cache size increment code that can severely degrade +performance. Specifically, if the \ref H5AC_cache_config_t.min_clean_fraction +"min_clean_fraction" is large enough, it is possible that keeping the specified +fraction of the cache clean may generate enough flushes to seriously degrade +performance even though the hit rate is excellent. + +In the serial case, this is easily dealt with by selecting a very small \ref +H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" -- 0.01 for example +-- as this still avoids the "metadata blizzard" phenomenon that appears when the +cache fills with dirty metadata and must then flush all of it before evicting an +entry to make space for a new entry. + +The problem is more difficult in the parallel case, as the \ref +H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" is used to ensure +that the cache contains clean entries that can be evicted to make space for new +entries when metadata writes are forbidden -- i.e. between sync points. + +This issue was discovered shortly before release 1.8.3 and an automated solution +has not been implemented. Should it become an issue for an application, try +manually setting the cache size to ~1.5 times the maximum working set size for +the application, and leave \ref H5AC_cache_config_t.min_clean_fraction +"min_clean_fraction" set to 0.3. + +You can approximate the working set size of your application via repeated calls +to H5Fget_mdc_size() and H5Fget_mdc_hit_rate() while running your program with +the cache resize code enabled. The maximum value returned by H5Fget_mdc_size() +should be a reasonable approximation -- particularly if the associated hit rate +is good. In the parallel case, there is also an interaction between \c +min_clean_fraction and \ref H5AC_cache_config_t.dirty_bytes_threshold +"dirty_bytes_threshold". Absent calls to H5Fflush() (discussed above), the upper +bound on the amount of dirty data in the metadata caches will oscillate between +(1 - \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction") times +current maximum cache size, and that value plus the \ref +H5AC_cache_config_t.dirty_bytes_threshold "dirty_bytes_threshold". Needless to +say, it will be best if the \ref H5AC_cache_config_t.min_size "min_size", \ref +H5AC_cache_config_t.min_clean_fraction "min_clean_fraction", and the \ref +H5AC_cache_config_t.dirty_bytes_threshold "dirty_bytes_threshold" +are chosen so that the cache can't fill with dirty data. + +\subsection defaults Default Metadata Cache Configuration + +Starting with release 1.8.3, HDF5 provides different default metadata cache +configurations depending on whether the library is compiled for serial or +parallel. + +The default configuration for the serial case is as follows: + +\code{.c} +{ + /* int version = */ H5C__CURR_AUTO_SIZE_CTL_VER, + /* hbool_t rpt_fcn_enabled = */ FALSE, + /* hbool_t open_trace_file = */ FALSE, + /* hbool_t close_trace_file = */ FALSE, + /* char trace_file_name[] = */ "", + /* hbool_t evictions_enabled = */ TRUE, + /* hbool_t set_initial_size = */ TRUE, + /* size_t initial_size = */ ( 2 * 1024 * 1024), + /* double min_clean_fraction = */ 0.01, + /* size_t max_size = */ (32 * 1024 * 1024), + /* size_t min_size = */ ( 1 * 1024 * 1024), + /* long int epoch_length = */ 50000, + /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold, + /* double lower_hr_threshold = */ 0.9, + /* double increment = */ 2.0, + /* hbool_t apply_max_increment = */ TRUE, + /* size_t max_increment = */ (4 * 1024 * 1024), + /* enum H5C_cache_flash_incr_mode */ + /* flash_incr_mode = */ H5C_flash_incr__add_space, + /* double flash_multiple = */ 1.4, + /* double flash_threshold = */ 0.25, + /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold, + /* double upper_hr_threshold = */ 0.999, + /* double decrement = */ 0.9, + /* hbool_t apply_max_decrement = */ TRUE, + /* size_t max_decrement = */ (1 * 1024 * 1024), + /* int epochs_before_eviction = */ 3, + /* hbool_t apply_empty_reserve = */ TRUE, + /* double empty_reserve = */ 0.1, + /* int dirty_bytes_threshold = */ (256 * 1024) +} +\endcode + +The default configuration for the parallel case is as follows: + +\code{.c} +{ + /* int version = */ H5C__CURR_AUTO_SIZE_CTL_VER, + /* hbool_t rpt_fcn_enabled = */ FALSE, + /* hbool_t open_trace_file = */ FALSE, + /* hbool_t close_trace_file = */ FALSE, + /* char trace_file_name[] = */ "", + /* hbool_t evictions_enabled = */ TRUE, + /* hbool_t set_initial_size = */ TRUE, + /* size_t initial_size = */ ( 2 * 1024 * 1024), + /* double min_clean_fraction = */ 0.3, + /* size_t max_size = */ (32 * 1024 * 1024), + /* size_t min_size = */ ( 1 * 1024 * 1024), + /* long int epoch_length = */ 50000, + /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold, + /* double lower_hr_threshold = */ 0.9, + /* double increment = */ 2.0, + /* hbool_t apply_max_increment = */ TRUE, + /* size_t max_increment = */ (4 * 1024 * 1024), + /* enum H5C_cache_flash_incr_mode */ + /* flash_incr_mode = */ H5C_flash_incr__add_space, + /* double flash_multiple = */ 1.0, + /* double flash_threshold = */ 0.25, + /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold, + /* double upper_hr_threshold = */ 0.999, + /* double decrement = */ 0.9, + /* hbool_t apply_max_decrement = */ TRUE, + /* size_t max_decrement = */ (1 * 1024 * 1024), + /* int epochs_before_eviction = */ 3, + /* hbool_t apply_empty_reserve = */ TRUE, + /* double empty_reserve = */ 0.1, + /* int dirty_bytes_threshold = */ (256 * 1024) +} +\endcode + +The default serial configuration should be adequate for most serial HDF5 users. + +The same may not be true for the default parallel configuration due to the +interaction between the \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" and the cache size increase code. See +the Interactions section for further details. + +Should you need to change the default configuration, it can be found in +H5ACprivate.h. Look for the definition of H5AC__DEFAULT_RESIZE_CONFIG. + +\section controlling Controlling the New Metadata Cache Size From Your Program + +You have already seen how \ref H5AC_cache_config_t has facilities that allow you +to control the metadata cache size directly. Use H5Fget_mdc_config() and +H5Fset_mdc_config() to get and set the metadata cache configuration on an open +file. Use H5Pget_mdc_config() and H5Pset_mdc_config() to get and set the initial +metadata cache configuration in a file access property list. Recall that this +list contains configuration data used when opening a file. + +Use H5Fget_mdc_hit_rate() to get the average hit rate since the last time the +hit rate stats were reset. This happens automatically at the beginning of each +epoch if the adaptive cache resize code is enabled. You can also do it manually +with H5Freset_mdc_hit_rate_stats(). Be careful about doing this if the adaptive +cache resize code is enabled, as you may confuse it. + +Use H5Fget_mdc_size() to get metadata cache size data on an open file. + +Finally, note that cache size and cache footprint are two different things -- in +my tests, the cache footprint (as inferred from the UNIX \c top command) is +typically about three times the maximum cache size. I haven't tracked it down +yet, but I would guess that most of this is due to the very small typical cache +entry size combined with the rather large size of the cache entry header +structure. This should be investigated further, but there are other matters of +higher priority. + +\section news New Metadata Cache Debugging Facilities + +The new metadata cache has a variety of debugging facilities that may be of +use. I doubt that any other than the report function and the trace file will +ever be accessible via the API, but they are relatively easy to turn on in the +source code. + +Note that none of this should be viewed as supported -- it is described here on +the off chance that you want to use it, but you are on your own if you do. Also, +there are no promises as to consistency between versions. + +As mentioned above, you can use the \ref H5AC_cache_config_t.rpt_fcn_enabled "rpt_fcn_enabled" field of the +configuration structure to enable the default reporting function +(H5C_def_auto_resize_rpt_fcn() in H5C.c). If this function doesn't work for you, +you will have to write your own. In particular, remember that it uses \c stdout, +so it will probably be unhappy under Windows. + +Again, remember that this facility is not supported. Further, it is likely to +change every time I do any serious work on the cache. + +There is also an extensive statistics collection code. Use +H5C_COLLECT_CACHE_STATS and H5C_COLLECT_CACHE_ENTRY_STATS in H5Cprivate.h to +turn this on. If you also turn on H5AC_DUMP_STATS_ON_CLOSE in H5ACprivate.h, +stats will be dumped when you close a file. Alternatively you can call +H5C_stats() and H5C_stats__reset() within the library to dump and reset +stats. Both of these functions are defined in H5C.c. + +Finally, the cache also contains an extensive sanity checking code. Much of this +is turned on when you compile in debug mode, but to enable the full suite, turn +on H5C_DO_SANITY_CHECKS in H5Cprivate.h. + +\section trouble Trouble Shooting + +Absent major bugs in the cache, the only troubleshooting you should have to do +is diagnosing and fixing problems with your cache configuration. + +Assuming it runs on your platform (I've only used it under Linux), the reporting +function is probably the most convenient diagnosis tool. However, since it is +unsupported code, I will not discuss it further beyond directing you to the +source (H5C_def_auto_resize_rpt_fcn() in H5C.c). + +Absent the reporting function, regular calls to H5Fget_mdc_hit_rate() should +give you a good idea of the hit rate over time. Remember that the hit rate stats +are reset at the end of each epoch (when adaptive cache resizing is enabled), so +you should expect some jitter. + +Similar calls to H5Fget_mdc_size() should allow you to monitor cache size and +the fraction of the current maximum cache size that is actually in use. + +If the hit rate is consistently low, and the cache it at its current maximum +size, increasing the maximum size is an obvious fix. + +If you see hit rate and cache size oscillations, try disabling adaptive cache +resizing and setting a fixed cache size a bit greater than the high end of the +cache size oscillations you observed. + +If the hit rate oscillations don't go away, you are probably looking at a +feature of your application that can't be helped without major changes to the +cache. Please send along a description of the situation. + +If the oscillations do go away, you may be able to come up with a configuration +that deals with the situation. If that fails, control the cache size manually, +and write to me, so I can try to develop an adaptive resize algorithm that works +in your case. + +Needless to say, you should give the cache a few epochs to adapt to +circumstances. If that is too slow for you, try manual cache size control. + +If you find it necessary to disable evictions, you may find it useful to enable +the internal statistics collection code mentioned above in the section on +debugging facilities. + +Amongst many other things, the stats code will report the maximum cache size, +and the average successful and unsuccessful search depths in the hash table. If +these latter figures are significantly above 1, you should increase the size of +the hash table. + + */
\ No newline at end of file diff --git a/doxygen/dox/OtherSpecs.dox b/doxygen/dox/OtherSpecs.dox new file mode 100644 index 0000000..e53f26e --- /dev/null +++ b/doxygen/dox/OtherSpecs.dox @@ -0,0 +1,11 @@ +/** \page IMG HDF5 Image and Palette Specification Version 1.2 + +\htmlinclude ImageSpec.html + +*/ + +/** \page TBL HDF5 Table Specification Version 1.0 + +\htmlinclude TableSpec.html + +*/ diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox new file mode 100644 index 0000000..754722e --- /dev/null +++ b/doxygen/dox/Overview.dox @@ -0,0 +1,32 @@ + +/** \mainpage notitle + +This is the documentation set for HDF5. You can +<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. + +This is the documention set for HDF5 in terms of specifications and software +developed and maintained by <a href="https://www.hdfgroup.org/">The HDF +Group</a>. It is impractical to document the entire HDF5 ecosystem in one place, +and you should also consult the documentation sets of the many outstanding +community projects. + +For a first contact with HDF5, the best place is to have a look at the \link +GettingStarted getting started \endlink page that shows you how to write and +compile your first program with HDF5. + +The \b main \b documentation is organized by documentation flavor. Most +technical documentation consists to varying degrees of information related to +<em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title +suggests, the \link RM Reference Manual \endlink is 100% reference material, +while the \link Cookbook \endlink is focused on tasks. The different guide-type +documents cover a mix of tasks, concepts, and reference, to help a certain +<em>audience</em> succeed. + +Finally, do not miss the search engine (top right-hand corner)! If you are +looking for a specific function, it'll take you there directly. If unsure, it'll +give you an idea of what's on offer and a few promising leads. + +\par ToDo List + There is plenty of <a href="./todo.html">unfinished business</a>. + +*/ diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox new file mode 100644 index 0000000..054f4c6 --- /dev/null +++ b/doxygen/dox/ReferenceManual.dox @@ -0,0 +1,37 @@ +/** \page RM Reference Manual + +The functions provided by the HDF5 C-API are grouped into the following +\Emph{modules}: + +\li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A) +\li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D) +\li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S) +\li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T) +\li \ref H5E "Error Handling" — Functions for handling HDF5 errors (\ref H5E) +\li \ref H5F "Files" — Management of HDF5 files (\ref H5F) +\li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z) +\li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G) +\li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I) +\li \ref H5 "Library" — General purpose library functions (\ref H5) +\li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L) +\li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O) +\li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL) +\li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P) +\li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R) + +\par API Versioning + See \ref api-compat-macros + +\par Deprecated Functions and Types + A list of deprecated functions and types can be found + <a href="./deprecated.html">here</a>. + +\par Etiquette + Here are a few simple rules to follow: + \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.) + \li \Bold{Dynamic memory allocation:} ... + \li \Bold{Use of locations:} Identifier + name combo + +\cpp_c_api_note + +*/
\ No newline at end of file diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox new file mode 100644 index 0000000..bd7e849 --- /dev/null +++ b/doxygen/dox/Specifications.dox @@ -0,0 +1,21 @@ +/** \page SPEC Specifications + +\section DDL + +\li \ref DDLBNF110 "DDL in BNF through HDF5 1.10" + +\section File Format + +\li \ref FMT1 "HDF5 File Format Specification Version 1.0" +\li \ref FMT11 "HDF5 File Format Specification Version 1.1" +\li \ref FMT2 "HDF5 File Format Specification Version 2.0" +\li \ref FMT3 "HDF5 File Format Specification Version 3.0" + +\section Other + +\li \ref IMG "HDF5 Image and Palette Specification Version 1.2" +\li \ref TBL "HDF5 Table Specification Version 1.0" +\li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> + HDF5 Dimension Scale Specification</a> + +*/
\ No newline at end of file diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox new file mode 100644 index 0000000..2bda175 --- /dev/null +++ b/doxygen/dox/TechnicalNotes.dox @@ -0,0 +1,20 @@ +/** \page TN Technical Notes + +\li \link api-compat-macros API Compatibility Macros \endlink +\li \ref TNMDC "Metadata Caching in HDF5" +\li \ref MT "Thread Safe library" +\li \ref VFL "Virtual File Layer" + + */ + +/** \page MT HDF5 Thread Safe library + +\htmlinclude ThreadSafeLibrary.html + +*/ + +/** \page VFL HDF5 Virtual File Layer + +\htmlinclude VFL.html + +*/ diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox index 6b85ccb..4a1578d 100644 --- a/doxygen/dox/api-compat-macros.dox +++ b/doxygen/dox/api-compat-macros.dox @@ -1,5 +1,4 @@ /** \page api-compat-macros API Compatibility Macros - \tableofcontents \section audience Audience The target audience for this document has existing applications that use the diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox deleted file mode 100644 index 83fc323..0000000 --- a/doxygen/dox/mainpage.dox +++ /dev/null @@ -1,36 +0,0 @@ -/*! \mainpage API Documentation for HDF5 Version 1.13 (Draft) - * - * \todo Fix the search form for server deployments. - * \todo Make it mobile-friendly - * - * \section intro_sec Introduction - * - * \todo Write an introduction. - * - * \section quick_links Quick Links - * - * <ul> - * <li>\ref PDT "Predefined Datatypes"</li> - * <li>\ref api-compat-macros "API Compatibility Macros"</li> - * <li><a href="https://hdf5.wiki/">HDF5 Wiki</a></li> - * </ul> - * - * \section using_locations The Use of Locations (Identifier + Name) in the HDF5 API - * - * \todo Make this crystal clear! - * - * \section cpp_note Programming Note for C++ Developers Using C Functions - * - * If a C routine that takes a function pointer as an argument is called from - * within C++ code, the C routine should be returned from normally. - * - * Examples of this kind of routine include callbacks such as H5Pset_elink_cb() - * and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2(). - * - * Exiting the routine in its normal fashion allows the HDF5 C library to clean - * up its work properly. In other words, if the C++ application jumps out of - * the routine back to the C++ \c catch statement, the library is not given the - * opportunity to close any temporary data structures that were set up when the - * routine was called. The C++ application should save some state as the - * routine is started so that any problem that occurs might be diagnosed. - */
\ No newline at end of file diff --git a/doxygen/examples/FF-IH_FileGroup.gif b/doxygen/examples/FF-IH_FileGroup.gif Binary files differnew file mode 100644 index 0000000..b0d76f5 --- /dev/null +++ b/doxygen/examples/FF-IH_FileGroup.gif diff --git a/doxygen/examples/FF-IH_FileObject.gif b/doxygen/examples/FF-IH_FileObject.gif Binary files differnew file mode 100644 index 0000000..8eba623 --- /dev/null +++ b/doxygen/examples/FF-IH_FileObject.gif diff --git a/doxygen/examples/FileFormatSpecChunkDiagram.jpg b/doxygen/examples/FileFormatSpecChunkDiagram.jpg Binary files differnew file mode 100644 index 0000000..03fd90a --- /dev/null +++ b/doxygen/examples/FileFormatSpecChunkDiagram.jpg diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html new file mode 100644 index 0000000..2d3ffbe --- /dev/null +++ b/doxygen/examples/H5.format.1.0.html @@ -0,0 +1,4050 @@ +<html> + <head> + <title> + HDF5 File Format Specification + </title> + </head> + <body bgcolor="#FFFFFF"> + + <center> + <table border=0 width=90%> + <tr> + <td valign=top> + <ol type=I> + <li><a href="#Intro">Introduction</a> + <li><a href="#BootBlock">Disk Format Level 0 - File Signature and Super Block</a> + <li><a href="#Group">Disk Format Level 1 - File Infrastructure</a> + <font size=-2> + <ol type=A> + <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> + <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> + <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> + <li><a href="#LocalHeap">Disk Format Level 1D - Local Heaps</a> + <li><a href="#GlobalHeap">Disk Format Level 1E - Global Heap</a> + <li><a href="#FreeSpaceIndex">Disk Format Level 1F - Free-space Index</a> + </ol> + </font> + <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> + <font size=-2> + <ol type=A> + <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> + <ol type=1> + <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> + <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> +<!-- + <li><a href="#DataSpaceMessage">Name: Complex Dataspace</a> --> <!-- 0x0002 --> + <li><a href="#DataTypeMessage">Name: Datatype</a> <!-- 0x0003 --> + <li><a href="#FillValueMessage">Name: Data Storage - Fill Value</a> <!-- 0x0004 --> + <li><a href="#ReservedMessage_0005">Name: Reserved - not assigned yet</a> <!-- 0x0005 --> + </ol> + </ol> + </font> + </ol> + </td><td> </td><td valign=top> + <ol type=I> + + <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> + <font size=-2><i>(Continued)</i> + <ol type=A> + <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> + <ol type=1> + <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> <!-- 0x0006 --> + <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> + <li><a href="#LayoutMessage">Name: Data Storage - Layout</a> <!-- 0x0008 --> + <li><a href="#ReservedMessage_0009">Name: Reserved - not assigned yet</a> <!-- 0x0009 --> + <li><a href="#ReservedMessage_000A">Name: Reserved - not assigned yet</a> <!-- 0x000a --> + <li><a href="#FilterMessage">Name: Data Storage - Filter Pipeline</a> <!-- 0x000b --> + <li><a href="#AttributeMessage">Name: Attribute</a> <!-- 0x000c --> + <li><a href="#NameMessage">Name: Object Name</a> <!-- 0x000d --> + <li><a href="#ModifiedMessage">Name: Object Modification Date and Time</a> <!-- 0x000e --> + <li><a href="#SharedMessage">Name: Shared Object Message</a> <!-- 0x000f --> + <li><a href="#ContinuationMessage">Name: Object Header Continuation</a> <!-- 0x0010 --> + <li><a href="#SymbolTableMessage">Name: Group Message</a> <!-- 0x0011 --> + </ol> + <li><a href="#SharedObjectHeader">Disk Format: Level 2b - Shared Data Object Headers</a> + <li><a href="#DataStorage">Disk Format: Level 2c - Data Object Data Storage</a> + </ol> + </font> + </ol> +</td></tr> +</table> +</center> + +<br><br> + + + <h2>Introduction</h2> + + <table align=right width=100> + <tr><td> </td><td align=center> + <hr> + <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace=15 vspace=15> + </td><td> </td></tr> + <tr><td> </td><td align=center> + <strong>Figure 1:</strong> Relationships among the HDF5 root group, other groups, and objects + <hr> + </td><td> </td></tr> + + <tr><td> </td><td align=center> + <img src="FF-IH_FileObject.gif" alt="HDF5 Objects" hspace=15 vspace=15> + </td><td> </td></tr> + <tr><td> </td><td align=center> + <strong>Figure 2:</strong> HDF5 objects -- datasets, datatypes, or dataspaces + <hr> + </td><td> </td></tr> + </table> + + + <P>The format of an HDF5 file on disk encompasses several + key ideas of the HDF4 and AIO file formats as well as + addressing some shortcomings therein. The new format is + more self-describing than the HDF4 format and is more + uniformly applied to data objects in the file. + + <P>An HDF5 file appears to the user as a directed graph. + The nodes of this graph are the higher-level HDF5 objects + that are exposed by the HDF5 APIs: + + <ul> + <li>Groups + <li>Datasets + <li>Datatypes + <li>Dataspaces + </ul> + + <P>At the lowest level, as information is actually written to the disk, + an HDF5 file is made up of the following objects: + <ul> + <li>A super block + <li>B-tree nodes (containing either symbol nodes or raw data chunks) + <li>Object headers + + <li>Collections + <li>Local heaps + <li>Free space + </ul> + + The HDF5 library uses these lower-level objects to represent the + higher-level objects that are then presented to the user or + to applications through the APIs. + For instance, a group is an object header that contains a message that + points to a local heap and to a B-tree which points to symbol nodes. + A dataset is an object header that contains messages that describe + datatype, space, layout, filters, external files, fill value, etc + with the layout message pointing to either a raw data chunk or to a + B-tree that points to raw data chunks. + + + <h3>This Document</h3> + + <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>. + + +<!-- +<blockquote> +<pre> + +Elena> NOTE: give reference to the detailed discussion of the B-trees +Elena> when needed. Right now we do not have specification (only general one) +Elena> for the Symbol Table B-trees and B-trees used to manage chunked datasets. +Elena> B-trees +Elena> General Discussion +Elena> Object related discussions +Elena> Symbol Tables +Elena> Global heap +Elena> "Free-space object" + + +</pre> +</blockquote> +--> + + + + <P>Three levels of information comprise the file format. + Level 0 contains basic information for identifying and + defining information about the file. Level 1 information contains + the group information (stored as a B-tree) and is used as the + index for all the objects in the file. Level 2 is the rest + of the file and contains all of the data objects, with each object + partitioned into header information, also known as + <em>meta information</em>, and data. + + <p>The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans + in the table. There are three exceptions: (1) The size may be + overridden by specifying a size in parentheses, (2) the size of + addresses is determined by the <em>Size of Offsets</em> field + in the super block, and (3) the size of size fields is determined + by the <em>Size of Lengths</em> field in the super block. + + + +<br><br> +<br><br> + + + <h2><a name="BootBlock"> + Disk Format: Level 0 - File Signature and Super Block</a></h2> + + <P>The super block may begin at certain predefined offsets within + the HDF5 file, allowing a block of unspecified content for + users to place additional information at the beginning (and + end) of the HDF5 file without limiting the HDF5 library's + ability to manage the objects within the file itself. This + feature was designed to accommodate wrapping an HDF5 file in + another file format or adding descriptive information to the + file without requiring the modification of the actual file's + information. The super block is located by searching for the + HDF5 file signature at byte offset 0, byte offset 512 and at + successive locations in the file, each a multiple of two of + the previous location, i.e. 0, 512, 1024, 2048, etc. + + <P>The super block is composed of a file signature, followed by + super block and group version numbers, information + about the sizes of offset and length values used to describe + items within the file, the size of each group page, + and a group entry for the root object in the file. + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <B>HDF5 Super Block Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>HDF5 File Signature (8 bytes)<br><br></td> + </tr> + + <tr align=center> + <td>Version # of Super Block</td> + <td>Version # of Global Free-space Storage</td> + <td>Version # of Group</td> + <td>Reserved</td> + </tr> + + <tr align=center> + <td>Version # of Shared Header Message Format</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>Reserved (zero)</td> + </tr> + + <tr align=center> + <td colspan=2>Group Leaf Node K</td> + <td colspan=2>Group Internal Node K</td> + </tr> + + <tr align=center> + <td colspan=4>File Consistency Flags</td> + </tr> + + <tr align=center> + <td colspan=4>Base Address*</td> + </tr> + + <tr align=center> + <td colspan=4>Address of Global Free-space Heap*</td> + </tr> + + <tr align=center> + <td colspan=4>End of File Address*</td> + </tr> + + <tr align=center> + <td colspan=4>Driver Information Block Address*</td> + </tr> + + <tr align=center> + <td colspan=4>Root Group Address*</td> + </tr> + </table> + + <table width="80%" border=0> + <tr><td> + <div align=right> + (Items marked with an asterisk (*) in the above table + <br> + are of the size specified in "Size of Offsets.") + </div> + </td></tr> + </table> + </center> + + <p> + <center> + <table width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>File Signature</td> + <td>This field contains a constant value and can be used to + quickly identify a file as being an HDF5 file. The + constant value is designed to allow easy identification of + an HDF5 file and to allow certain types of data corruption + to be detected. The file signature of an HDF5 file always + contains the following values: + + <br><br><center> + <table border align=center cellpadding=4 width="100%"> + <tr align=center> + <td>decimal</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align=center> + <td>hexadecimal</td> + <td width="8%">89</td> + <td width="8%">48</td> + <td width="8%">44</td> + <td width="8%">46</td> + <td width="8%">0d</td> + <td width="8%">0a</td> + <td width="8%">1a</td> + <td width="8%">0a</td> + </tr> + + <tr align=center> + <td>ASCII C Notation</td> + <td width="8%">\211</td> + <td width="8%">H</td> + <td width="8%">D</td> + <td width="8%">F</td> + <td width="8%">\r</td> + <td width="8%">\n</td> + <td width="8%">\032</td> + <td width="8%">\n</td> + </tr> + </table> + </center> + <br> + + This signature both identifies the file as an HDF5 file + and provides for immediate detection of common + file-transfer problems. The first two bytes distinguish + HDF5 files on systems that expect the first two bytes to + identify the file type uniquely. The first byte is + chosen as a non-ASCII value to reduce the probability + that a text file may be misrecognized as an HDF5 file; + also, it catches bad file transfers that clear bit + 7. Bytes two through four name the format. The CR-LF + sequence catches bad file transfers that alter newline + sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse + of the CR-LF translation problem. (This is a direct + descendent of the PNG file signature.)</td> + </tr> + + <tr valign=top> + <td>Version Number of the Super Block</td> + <td>This value is used to determine the format of the + information in the super block. When the format of the + information in the super block is changed, the version number + is incremented to the next integer and can be used to + determine how the information in the super block is + formatted.</td> + </tr> + + <tr valign=top> + <td>Version Number of the Global Free-space Heap</td> + <td>This value is used to determine the format of the + information in the Global Free-space Heap.</td> + </tr> + + <tr valign=top> + <td>Version Number of the Group</td> + <td>This value is used to determine the format of the + information in the Group. When the format of + the information in the Group is changed, the + version number is incremented to the next integer and can be + used to determine how the information in the Group + is formatted.</td> + </tr> + + <tr valign=top> + <td>Version Number of the Shared Header Message Format</td> + <td>This value is used to determine the format of the + information in a shared object header message, which is + stored in the global small-data heap. Since the format + of the shared header messages differs from the private + header messages, a version number is used to identify changes + in the format.</td> + </tr> + + <tr valign=top> + <td>Size of Offsets</td> + <td>This value contains the number of bytes used to store + addresses in the file. The values for the addresses of + objects in the file are offsets relative to a base address, + usually the address of the super block signature. This + allows a wrapper to be added after the file is created + without invalidating the internal offset locations.</td> + </tr> + + <tr valign=top> + <td>Size of Lengths</td> + <td>This value contains the number of bytes used to store + the size of an object.</td> + </tr> + + <tr valign=top> + <td>Group Leaf Node K</td> + <td>Each leaf node of a group B-tree will have at + least this many entries but not more than twice this + many. If a group has a single leaf node then it + may have fewer entries.</td> + </tr> + + <tr valign=top> + <td>Group Internal Node K</td> + <td>Each internal node of a group B-tree will have + at least K pointers to other nodes but not more than 2K + pointers. If the group has only one internal + node then it might have fewer than K pointers.</td> + </tr> + + <tr valign=top> + <td>Bytes per B-tree Page</td> + <td>This value contains the number of bytes used for symbol + pairs per page of the B-trees used in the file. All + B-tree pages will have the same size per page. + <br> + For 32-bit file offsets, 340 objects is the maximum + per 4KB page; for 64-bit file offset, 254 objects will fit + per 4KB page. In general, the equation is: + <br> + <code> <<i>number of objects</i>> = + <br> + FLOOR((<<i>page size</i>> - <<i>offset size</i>>) / + <br> + (<<i>Symbol size</i>> + <<i>offset size</i>>)) + - 1 </code></td> + </tr> + + <tr valign=top> + <td>File Consistency Flags</td> + <td>This value contains flags to indicate information + about the consistency of the information contained + within the file. Currently, the following bit flags are + defined: + <ul> + <li>Bit 0 set indicates that the file is opened for + write-access. + <li>Bit 1 set indicates that the file has + been verified for consistency and is guaranteed to be + consistent with the format defined in this document. + <li>Bits 2-31 are reserved for future use. + </ul> + Bit 0 should be + set as the first action when a file is opened for write + access and should be cleared only as the final action + when closing a file. Bit 1 should be cleared during + normal access to a file and only set after the file's + consistency is guaranteed by the library or a + consistency utility.</td> + </tr> + + <tr valign=top> + <td>Base Address</td> + <td>This is the absolute file address of the first byte of + the HDF5 data within the file. The library currently + constrains this value to be the absolute file address + of the super block itself when creating new files; + future versions of the library may provide greater + flexibility. Unless otherwise noted, + all other file addresses are relative to this base + address.</td> + </tr> + + <tr valign=top> + <td>Address of Global Free-space Heap</td> + <td>Free-space management is not yet defined in the HDF5 + file format and is not handled by the library. + Currently this field always contains the + undefined address <code>0xfff...ff</code>. +<!-- + <td>This value contains the relative address of the B-tree + used to manage the blocks of data which are unused in the + file currently. The free-space heap is used to manage the + blocks of bytes at the file-level which become unused when + objects are moved within the file.</td> +--> + </tr> + + <tr valign=top> + <td>End of File Address</td> + <td>This is the relative file address of the first byte past + the end of all HDF5 data. It is used to determine whether a + file has been accidently truncated and as an address where + file data allocation can occur if the free list is not + used.</td> + </tr> + + <tr valign=top> + <td>Driver Information Block Address</td> + <td>This is the relative file address of the file driver + information block which contains driver-specific + information needed to reopen the file. If there is no + driver information block then this entry should be the + undefined address (all bits set).</td> + </tr> + + <tr valign=top> + <td>Root Group Address</td> + <td>This is the address of the root group (described later + in this document), which serves as the entry point into + the group graph.</td> + </tr> + </table> + </center> + + + <p>The <em>file driver information block</em> is an optional region of the + file which contains information needed by the file driver in + order to reopen a file. The format of the file driver information + block is: + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <B>Driver Information Block</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr align=center> + <td colspan=4>Driver Information Size (4 bytes)</td> + </tr> + + <tr align=center> + <td colspan=4><br>Driver Identification (8 bytes)<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Driver Information<br><br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version</td> + <td>The version number of the driver information block. The + file format documented here is version zero.</td> + </tr> + + <tr valign=top> + <td>Driver Information Size</td> + <td>The size in bytes of the Driver Information part of this + structure.</td> + </tr> + + <tr valign=top> + <td>Driver Identification</td> + <td>This is an eight-byte ASCII string without null + termination which identifies the driver and version number + of the Driver Information block. The predefined drivers + supplied with the HDF5 library are identified by the + letters <code>NCSA</code> followed by the first four characters of + the driver name. If the Driver Information block is not + the original version then the last letter(s) of the + identification will be replaced by a version number in + ASCII. + For example, the various versions of the <em>family driver</em> + will be identified by <code>NCSAfami</code>, <code>NCSAfam0</code>, + <code>NCSAfam1</code>, etc. + (<code>NCSAfami</code> is simply <code>NCSAfamily</code> truncated + to eight characters. Subsequent identifiers will be created by + substituting sequential numerical values for the final character, + starting with zero.) + <p> + Identification for user-defined drivers + is arbitrary but should be unique.</td> + </tr> + + <tr valign=top> + <td>Driver Information</td> + <td>Driver information is stored in a format defined by the + file driver and encoded/decoded by the driver callbacks + invoked from the <code>H5FD_sb_encode</code> and + <code>H5FD_sb_decode</code> functions.</td> + </tr> + </table> + </center> + + + <br><br> + <br><br> + + + <h2><a name="Group"> + Disk Format: Level 1 - File Infrastructure</a></h2> + <h3><a name="Btrees">Disk Format: Level 1A - B-link Trees and B-tree Nodes</a></h3> + + <p>B-link trees allow flexible storage for objects which tend to grow + in ways that cause the object to be stored discontiguously. B-trees + are described in various algorithms books including "Introduction to + Algorithms" by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. The B-link tree, in which the sibling nodes at a + particular level in the tree are stored in a doubly-linked list, + is described in the "Efficient Locking for Concurrent Operations + on B-trees" paper by Phillip Lehman and S. Bing Yao as published + in the <em>ACM Transactions on Database Systems</em>, Vol. 6, + No. 4, December 1981. + + <p>The B-link trees implemented by the file format contain one more + key than the number of children. In other words, each child + pointer out of a B-tree node has a left key and a right key. + The pointers out of internal nodes point to sub-trees while + the pointers out of leaf nodes point to symbol nodes and + raw data chunks. + Aside from that difference, internal nodes and leaf nodes + are identical. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>B-tree Nodes</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Node Signature</td> + + <tr align=center> + <td>Node Type</td> + <td>Node Level</td> + <td colspan=2>Entries Used</td> + + <tr align=center> + <td colspan=4>Address of Left Sibling</td> + + <tr align=center> + <td colspan=4>Address of Right Sibling</td> + + <tr align=center> + <td colspan=4>Key 0 (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 0</td> + + <tr align=center> + <td colspan=4>Key 1 (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 1</td> + + <tr align=center> + <td colspan=4>...</td> + + <tr align=center> + <td colspan=4>Key 2<em>K</em> (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 2<em>K</em></td> + + <tr align=center> + <td colspan=4>Key 2<em>K</em>+1 (variable size)</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Node Signature</td> + <td>The ASCII character string <code>TREE</code> is + used to indicate the + beginning of a B-link tree node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file.</td> + </tr> + + <tr valign=top> + <td>Node Type</td> + <td>Each B-link tree points to a particular type of data. + This field indicates the type of data as well as + implying the maximum degree <em>K</em> of the tree and + the size of each Key field. + <br> + <dl compact> + <dt>0 + <dd>This tree points to group nodes. + <dt>1 + <dd>This tree points to a new data chunk. + </dl> + </td> + </tr> + + <tr valign=top> + <td>Node Level</td> + <td>The node level indicates the level at which this node + appears in the tree (leaf nodes are at level zero). Not + only does the level indicate whether child pointers + point to sub-trees or to data, but it can also be used + to help file consistency checking utilities reconstruct + damanged trees.</td> + </tr> + + <tr valign=top> + <td>Entries Used</td> + <td>This determines the number of children to which this + node points. All nodes of a particular type of tree + have the same maximum degree, but most nodes will point + to less than that number of children. The valid child + pointers and keys appear at the beginning of the node + and the unused pointers and keys appear at the end of + the node. The unused pointers and keys have undefined + values.</td> + </tr> + + <tr valign=top> + <td>Address of Left Sibling</td> + <td>This is the file address of the left sibling of the + current node relative to the super block. If the current + node is the left-most node at this level then this field + is the undefined address (all bits set).</td> + </tr> + + <tr valign=top> + <td>Address of Right Sibling</td> + <td>This is the file address of the right sibling of the + current node relative to the super block. If the current + node is the right-most node at this level then this + field is the undefined address (all bits set).</td> + </tr> + + <tr valign=top> + <td>Keys and Child Pointers</td> + <td>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> + child pointers interleaved between the keys. The number + of keys and child pointers actually containing valid + values is determined by the <em>Entries Used</em> field. If + that field is <em>N</em> then the B-link tree contains + <em>N</em> child pointers and <em>N</em>+1 keys.</td> + </tr> + + <tr valign=top> + <td>Key</td> + <td>The format and size of the key values is determined by + the type of data to which this tree points. The keys are + ordered and are boundaries for the contents of the child + pointer; that is, the key values represented by child + <em>N</em> fall between Key <em>N</em> and Key + <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the + tree points. + <p> + The format of the key depends on the node type. + For nodes of node type 1, the key is formatted as follows: + <center> + <table> + <tr valign=top align=left> + <td width=40%>Bytes 1-4</td> + <td>Size of chunk in bytes.</td> + <tr valign=top align=left></tr> + <td>Bytes 4-8</td> + <td>Filter mask, a 32-bit bitfield indicating which + filters have been applied to that chunk.</td> + </tr><tr valign=top align=left> + <td><i>N</i> fields of 8 bytes each</td> + <td>A 64-bit index indicating the offset of the + chunk within the dataset where <i>N</i> is the number + of dimensions of the dataset. For example, if + a chunk in a 3-dimensional dataset begins at the + position <code>[5,5,5]</code>, there will be three + such 8-bit indices, each with the value of + <code>5</code>.</td> + </tr> + </table> + </center> + <p> + For nodes of node type 0, the key is formatted as follows: + <center> + <table> + <tr valign=top align=left> + <td width=40%>A single field of <i>Size of Lengths</i> + bytes</td> + <td>Indicates the byte offset into the local heap + for the first object name in the subtree which + that key describes.</td> + </tr> + </table> + </center> + </td> + </tr> + + <tr valign=top> + <td>Child Pointers</td> + <td>The tree node contains file addresses of subtrees or + data depending on the node level. Nodes at Level 0 point + to data addresses, either data chunk or group nodes. + Nodes at non-zero levels point to other nodes of the + same B-tree.</td> + </tr> + </table> + </center> + +<p> + Each B-tree node looks like this: + + <center> + <table> + <tr valign=top align=center> + <td>key[0]</td><td> </td> + <td>child[0]</td><td> </td> + <td>key[1]</td><td> </td> + <td>child[1]</td><td> </td> + <td>key[2]</td><td> </td> + <td>...</td><td> </td> + <td>...</td><td> </td> + <td>key[<i>N</i>-1]</td><td> </td> + <td>child[<i>N</i>-1]</td><td> </td> + <td>key[<i>N</i>]</td> + </tr> + </table> + </center> + + where child[<i>i</i>] is a pointer to a sub-tree (at a level + above Level 0) or to data (at Level 0). + Each key[<i>i</i>] describes an <i>item</i> stored by the B-tree + (a chunk or an object of a group node). The range of values + represented by child[<i>i</i>] are indicated by key[<i>i</i>] + and key[<i>i</i>+1]. + + + <p>The following question must next be answered: + "Is the value described by key[<i>i</i>] contained in + child[<i>i</i>-1] or in child[<i>i</i>]?" + The answer depends on the type of tree. + In trees for groups (node type 0) the object described by + key[<i>i</i>] is the greatest object contained in + child[<i>i</i>-1] while in chunk trees (node type 1) the + chunk described by key[<i>i</i>] is the least chunk in + child[<i>i</i>]. + + <p>That means that key[0] for group trees is sometimes unused; + it points to offset zero in the heap, which is always the + empty string and compares as "less-than" any valid object name. + + <p>And key[<i>N</i>] for chunk trees is sometimes unused; + it contains a chunk offset which compares as "greater-than" + any other chunk offset and has a chunk byte size of zero + to indicate that it is not actually allocated. + + + <h3><a name="SymbolTable">Disk Format: Level 1B - Group and Symbol Nodes</a></h3> + + <p>A group is an object internal to the file that allows + arbitrary nesting of objects (including other groups). + A group maps a set of names to a set of file + address relative to the base address. Certain meta data + for an object to which the group points can be duplicated + in the group symbol table in addition to the object header. + + <p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each + component in a group. The group entry for a + non-ultimate component points to the group containing + the next component. The group entry for the last + component points to the object being named. + + <p>A group is a collection of group nodes pointed + to by a B-link tree. Each group node contains entries + for one or more symbols. If an attempt is made to add a + symbol to an already full group node containing + 2<em>K</em> entries, then the node is split and one node + contains <em>K</em> symbols and the other contains + <em>K</em>+1 symbols. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Group Node (A Leaf of a B-tree)</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Node Signature</td> + + <tr align=center> + <td>Version Number</td> + <td>Reserved for Future Use</td> + <td colspan=2>Number of Symbols</td> + + <tr align=center> + <td colspan=4><br><br>Group Entries<br><br><br></td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Node Signature</td> + <td>The ASCII character string <code>SNOD</code> is + used to indicate the + beginning of a group node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file.</td> + </tr> + + <tr valign=top> + <td>Version Number</td> + <td>The version number for the group node. This + document describes version 1.</td> + </tr> + + <tr valign=top> + <td>Number of Symbols</td> + <td>Although all group nodes have the same length, + most contain fewer than the maximum possible number of + symbol entries. This field indicates how many entries + contain valid data. The valid entries are packed at the + beginning of the group node while the remaining + entries contain undefined values.</td> + </tr> + + <tr valign=top> + <td>Group Entries</td> + <td>Each symbol has an entry in the group node. + The format of the entry is described below.</td> + </tr> + </table> + </center> + + <h3><a name="SymbolTableEntry"> + Disk Format: Level 1C - Group Entry </a></h3> + + <p>Each group entry in a group node is designed + to allow for very fast browsing of stored objects. + Toward that design goal, the group entries + include space for caching certain constant meta data from the + object header. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Group Entry</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Name Offset (<size> bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Object Header Address</td> + </tr> + + <tr align=center> + <td colspan=4>Cache Type</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Scratch-pad Space (16 bytes)<br><br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Name Offset</td> + <td>This is the byte offset into the group local + heap for the name of the object. The name is null + terminated.</td> + </tr> + + <tr valign=top> + <td>Object Header Address</td> + <td>Every object has an object header which serves as a + permanent location for the object's meta data. In addition + to appearing in the object header, some meta data can be + cached in the scratch-pad space.</td> + </tr> + + <tr valign=top> + <td>Cache Type</td> + <td>The cache type is determined from the object header. + It also determines the format for the scratch-pad space. + <br> + <dl compact> + <dt>0 + <dd>No data is cached by the group entry. This + is guaranteed to be the case when an object header + has a link count greater than one. + + <dt>1 + <dd>Object header meta data is cached in the group + entry. This implies that the group + entry refers to another group. + + <dt>2 + <dd>The entry is a symbolic link. The first four bytes + of the scratch-pad space are the offset into the local + heap for the link value. The object header address + will be undefined. + + <dt><em>N</em> + <dd>Other cache values can be defined later and + libraries that do not understand the new values will + still work properly. + </dl> + </td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>These four bytes are present so that the scratch-pad + space is aligned on an eight-byte boundary. They are + always set to zero.</td> + </tr> + + <tr valign=top> + <td>Scratch-pad Space</td> + <td>This space is used for different purposes, depending + on the value of the Cache Type field. Any meta-data + about a dataset object represented in the scratch-pad + space is duplicated in the object header for that + dataset. This meta data can include the datatype + and the size of the dataspace for a dataset whose datatype + is atomic and whose dataspace is fixed and less than + four dimensions. + Furthermore, no data is cached in the group + entry scratch-pad space if the object header for + the group entry has a link count greater than + one.</td> + </tr> + </table> + </center> + + <h4>Format of the Scratch-pad Space</h4> + + <p>The group entry scratch-pad space is formatted + according to the value in the Cache Type field. + + <p>If the Cache Type field contains the value zero + (<code>0</code>) then no information is + stored in the scratch-pad space. + + <p>If the Cache Type field contains the value one + (<code>1</code>), then the scratch-pad space + contains cached meta data for another object header + in the following format: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Object Header Scratch-pad Format</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Address of B-tree</td> + + <tr align=center> + <td colspan=4>Address of Name Heap</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Address of B-tree</td> + <td>This is the file address for the root of the + group's B-tree.</td> + </tr> + + <tr valign=top> + <td>Address of Name Heap</td> + <td>This is the file address for the group's local + heap, in which are stored the symbol names.</td> + </tr> + </table> + </center> + + + <p>If the Cache Type field contains the value two + (<code>2</code>), then the scratch-pad space + contains cached meta data for another symbolic link + in the following format: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Symbolic Link Scratch-pad Format</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Offset to Link Value</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Offset to Link Value</td> + <td>The value of a symbolic link (that is, the name of the + thing to which it points) is stored in the local heap. + This field is the 4-byte offset into the local heap for + the start of the link value, which is null terminated.</td> + </tr> + </table> + </center> + + <h3><a name="LocalHeap">Disk Format: Level 1D - Local Heaps</a></h3> + + <p>A heap is a collection of small heap objects. Objects can be + inserted and removed from the heap at any time. + The address of a heap does not change once the heap is created. + References to objects are stored in the group table; + the names of those objects are stored in the local heap. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Local Heaps</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Heap Signature</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved (zero)</td> + </tr> + + <tr align=center> + <td colspan=4>Data Segment Size</td> + </tr> + + <tr align=center> + <td colspan=4>Offset to Head of Free-list (<size> bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Address of Data Segment</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Heap Signature</td> + <td>The ASCII character string <code>HEAP</code> + is used to indicate the + beginning of a heap. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file.</td> + </tr> + + <tr valign=top> + <td>Data Segment Size</td> + <td>The total amount of disk memory allocated for the heap + data. This may be larger than the amount of space + required by the object stored in the heap. The extra + unused space holds a linked list of free blocks.</td> + </tr> + + <tr valign=top> + <td>Offset to Head of Free-list</td> + <td>This is the offset within the heap data segment of the + first free block (or all 0xff bytes if there is no free + block). The free block contains <size> bytes that + are the offset of the next free chunk (or all 0xff bytes + if this is the last free chunk) followed by <size> + bytes that store the size of this free chunk.</td> + </tr> + + <tr valign=top> + <td>Address of Data Segment</td> + <td>The data segment originally starts immediately after + the heap header, but if the data segment must grow as a + result of adding more objects, then the data segment may + be relocated, in its entirety, to another part of the + file.</td> + </tr> + </table> + </center> + + <p>Objects within the heap should be aligned on an 8-byte boundary. + + <h3><a name="GlobalHeap">Disk Format: Level 1E - Global Heap</a></h3> + + <p>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The + global heap was designed to satisfy these goals: + + <ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap + objects will typically be shared among several datasets, it is + probable that the object will be accessed repeatedly. + + <br><br> + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of + void pointers will have a global heap object for each + pointer. Reading the entire set of void pointer objects + should result in a few large I/O requests instead of one small + I/O request for each object. + + <br><br> + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed + for other uses. + <br><br> + </ol> + + <p>The implementation of the heap makes use of the memory + management already available at the file level and combines that + with a new top-level object called a <em>collection</em> to + achieve Goal B. The global heap is the set of all collections. + Each global heap object belongs to exactly one collection and + each collection contains one or more global heap objects. For + the purposes of disk I/O and caching, a collection is treated as + an atomic object. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>A Global Heap Collection</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Magic Number</td> + </tr> + + <tr align=center> + <td>Version</td> + <td colspan=3>Reserved</td> + </td> + + <tr align=center> + <td colspan=4>Collection Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Global Heap Object 1 + <i>(described below)</i><br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Global Heap Object 2<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>...<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Global Heap Object <em>N</em><br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Global Heap Object 0 (free space)<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Magic Number</td> + <td>The magic number for global heap collections are the + four bytes <code>G</code>, <code>C</code>, <code>O</code>, + and <code>L</code>.</td> + </tr> + + <tr valign=top> + <td>Version</td> + <td>Each collection has its own version number so that new + collections can be added to old files. This document + describes version zero of the collections. + </tr> + + <tr valign=top> + <td>Collection Data Size</td> + <td>This is the size in bytes of the entire collection + including this field. The default (and minimum) + collection size is 4096 bytes which is a typical file + system block size and which allows for 170 16-byte heap + objects plus their overhead.</td> + </tr> + + <tr valign=top> + <td>Object 1 through <em>N</em></td> + <td>The objects are stored in any order with no + intervening unused space.</td> + </tr> + + <tr valign=top> + <td>Object 0</td> + <td>Object 0 (zero), when present, represents the free space in + the collection. Free space always appears at the end of + the collection. If the free space is too small to store + the header for Object 0 (described below) then the + header is implied and the collection contains no free space. + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Global Heap Object</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=2>Object ID</td> + <td colspan=2>Reference Count</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Object Data Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Object Data<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Object ID</td> + <td>Each object has a unique identification number within a + collection. The identification numbers are chosen so that + new objects have the smallest value possible with the + exception that the identifier <code>0</code> always refers to the + object which represents all free space within the + collection.</td> + </tr> + + <tr valign=top> + <td>Reference Count</td> + <td>All heap objects have a reference count field. An + object which is referenced from some other part of the + file will have a positive reference count. The reference + count for Object 0 is always zero.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>Zero padding to align next field on an 8-byte + boundary.</td> + </tr> + + <tr valign=top> + <td>Object Size</td> <td>This is the size of the the fields + above plus the object data stored for the object. The + actual storage size is rounded up to a multiple of + eight.</td> + </tr> + + <tr valign=top> + <td>Object Data</td> + <td>The object data is treated as a one-dimensional array + of bytes to be interpreted by the caller.</td> + </tr> + </table> + </center> + + <h3><a name="FreeSpaceIndex">Disk Format: Level 1F - Free-space Heap</a></h3> + + <p>The Free-space Index is a collection of blocks of data, + dispersed throughout the file, which are currently not used by + any file objects. + + <p>The super block contains a pointer to root of the free-space description; + that pointer is currently (i.e., in HDF5 Release 1.2) required + to be the undefined address <code>0xfff...ff</code>. + + <p>The free-sapce index is not otherwise publicly defined at this time. + + + <!-- + <p>The Free-space Index is a collection of blocks of data, + dispersed throughout the file, which are currently not used by + any file objects. The blocks of data are indexed by a B-tree of + their length within the file. + + + <p>Each B-tree page is composed of the following entries and + B-tree management information, organized as follows: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Free-space Heap Page</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Free-space Heap Signature</td> + <tr align=center> + <td colspan=4>B-tree Left-link Offset</td> + <tr align=center> + <td colspan=4><br>Length of Free-block #1<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-block #1<br> <br></td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4><br>Length of Free-block #n<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-block #n<br> <br></td> + <tr align=center> + <td colspan=4>"High" Offset</td> + <tr align=center> + <td colspan=4>Right-link Offset</td> + </table> + </center> + + <p> + <dl> + <dt> The elements of the free-space heap page are described below: + <dd> + <dl> + <dt>Free-space Heap Signature: (4 bytes) + <dd>The ASCII character string <code>FREE</code> + is used to indicate the + beginning of a free-space heap B-tree page. This gives + file consistency checking utilities a better chance of + reconstructing a damaged file. + + <dt>B-tree Left-link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of all offsets + in the B-link-tree which are smaller than the value of the + offset in entry #1. This value is also used to indicate a + leaf node in the B-link-tree by being set to all ones. + + <dt>Length of Free-block #n: (<length> bytes) + <dd>This value indicates the length of an unused block in + the file. + + <dt>Offset of Free-block #n: (<offset> bytes) + <dd>This value indicates the offset in the file of an + unused block in the file. + + <dt>"High" Offset: (4-bytes) + <dd>This offset is used as the upper bound on offsets + contained within a page when the page has been split. + + <dt>Right-link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of the next + child to the right of the parent of this group + page. When there is no node to the right, this value is + all zeros. + </dl> + </dl> + + <p>The algorithms for searching and inserting objects in the + B-tree pages are described fully in the Lehman and Yao paper, + which should be read to provide a full description of the + B-tree's usage. +--> + + +<br><br> +<br><br> + + + <h2><a name="DataObject">Disk Format: Level 2 - Data Objects </a></h2> + + <p>Data objects contain the real information in the file. These + objects compose the scientific data and other information which + are generally thought of as "data" by the end-user. All the + other information in the file is provided as a framework for + these data objects. + + <p>A data object is composed of header information and data + information. The header information contains the information + needed to interpret the data information for the data object as + well as additional "meta-data" or pointers to additional + "meta-data" used to describe or annotate each data object. + + <h3><a name="ObjectHeader"> + Disk Format: Level 2a - Data Object Headers</a></h3> + + <p>The header information of an object is designed to encompass + all the information about an object which would be desired to be + known, except for the data itself. This information includes + the dimensionality, number-type, information about how the data + is stored on disk (in external files, compressed, broken up in + blocks, etc.), as well as other information used by the library + to speed up access to the data objects or maintain a file's + integrity. The header of each object is not necessarily located + immediately prior to the object's data in the file and in fact + may be located in any position in the file. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Object Headers</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=1 width="25%">Version # of Object Header</td> + <td colspan=1 width="25%">Reserved</td> + <td colspan=2 width="50%">Number of Header Messages</td> + </tr> + <tr align=center> + <td colspan=4>Object Reference Count</td> + </tr> + <tr align=center> + <td colspan=4><br>Total Object Header Size<br><br></td> + </tr> + <tr align=center> + <td colspan=2>Header Message Type #1</td> + <td colspan=2>Size of Header Message Data #1</td> + </tr> + <tr align=center> + <td>Flags</td> + <td colspan=3>Reserved</td> + </tr> + <tr align=center> + <td colspan=4><br>Header Message Data #1<br><br></td> + </tr> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr align=center> + <td colspan=2>Header Message Type #n</td> + <td colspan=2>Size of Header Message Data #n</td> + </tr> + <tr align=center> + <td>Flags</td> + <td colspan=3>Reserved</td> + </tr> + <tr align=center> + <td colspan=4><br>Header Message Data #n<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version number of the object header</td> + <td>This value is used to determine the format of the + information in the object header. When the format of the + information in the object header is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>Always set to zero.</td> + </tr> + + <tr valign=top> + <td>Number of header messages</td> + <td>This value determines the number of messages listed in + this object header. This provides a fast way for software + to prepare storage for the messages in the header.</td> + </tr> + + <tr valign=top> + <td>Object Reference Count</td> + <td>This value specifies the number of references to this + object within the current file. References to the + data object from external files are not tracked.</td> + </tr> + + <tr valign=top> + <td>Total Object Header Size</td> + <td>This value specifies the total number of bytes of header + message data following this length field for the current + message as well as any continuation data located elsewhere + in the file.</td> + </tr> + + <tr valign=top> + <td>Header Message Type</td> + <td>The header message type specifies the type of + information included in the header message data following + the type along with a small amount of other information. + Bit 15 of the message type is set if the message is + constant (constant messages cannot be changed since they + may be cached in group entries throughout the + file). The header message types for the pre-defined + header messages will be included in further discussion + below.</td> + </tr> + + <tr valign=top> + <td>Size of Header Message Data</td> + <td>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size includes + padding bytes to make the message a multiple of eight + bytes.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>This is a bit field with the following definition: + <dl> + <dt><code>0</code> + <dd>If set, the message data is constant. This is used + for messages like the datatype message of a dataset. + <dt><code>1</code> + <dd>If set, the message is stored in the global heap and + the Header Message Data field contains a Shared Object + message and the Size of Header Message Data field + contains the size of that Shared Object message. + <dt><code>2-7</code> + <dd>Reserved + </dl> + </td> + + <tr valign=top> + <td>Header Message Data</td> + <td>The format and length of this field is determined by the + header message type and size respectively. Some header + message types do not require any data and this information + can be eliminated by setting the length of the message to + zero. The data is padded with enough zeros to make the + size a multiple of eight.</td> + </tr> + </table> + </center> + + <p>The header message types and the message data associated with + them compose the critical "meta-data" about each object. Some + header messages are required for each object while others are + optional. Some optional header messages may also be repeated + several times in the header itself, the requirements and number + of times allowed in the header will be noted in each header + message description below. + + <P>The following is a list of currently defined header messages: + + <hr> + <h4><a name="NILMessage">Name: NIL</a></h4> + <b>Type: </b>0x0000<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may be repeated.<br> + <b>Purpose and Description:</b> The NIL message is used to + indicate a message + which is to be ignored when reading the header messages for a data object. + [Probably one which has been deleted for some reason.]<br> + <b>Format of Data:</b> Unspecified.<br> + +<!-- Delete examples throughout doc + <b>Examples:</b> None. +--> + + + <hr> + <h4><a name="SimpleDataSpace">Name: Simple Dataspace</a></h4> + + <b>Type: </b>0x0001<br> + <b>Length:</b> Varies according to the number of dimensions, + as described in the following table<br> + <b>Status:</b> The <em>Simple Dataspace</em> message is required + and may not be repeated. This message is currently used with + datasets and named dataspaces.<br> + + <p>The <em>Simple Dataspace</em> message describes the number + of dimensions and size of each dimension that the data object + has. This message is only used for datasets which have a + simple, rectilinear grid layout; datasets requiring a more + complex layout (irregularly structured or unstructured grids, etc.) + must use the <em>Complex Dataspace</em> message for expressing + the space the dataset inhabits. + <i>(Note: The <em>Complex Dataspace</em> functionality is + not yet implemented (as of HDF5 Release 1.2). It is not described + in this document.)</i> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Simple Dataspace Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension Size #1 (<size> bytes)</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Dimension Size #n (<size> bytes)</td> + <tr align=center> + <td colspan=4>Dimension Maximum #1 (<size> bytes)</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Dimension Maximum #n (<size> bytes)</td> + <tr align=center> + <td colspan=4>Permutation Index #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Permutation Index #n</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version </td> + <td>This value is used to determine the format of the + Simple Dataspace Message. When the format of the + information in the message is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted.</td> + </tr> + + <tr valign=top> + <td>Dimensionality</td> + <td>This value is the number of dimensions that the data + object has.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. Bit 1 is used to indicate that + permutation indices are present for each dimension.</td> + </tr> + + <tr valign=top> + <td>Dimension Size #n (<size> bytes)</td> + <td>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension.</td> + </tr> + + <tr valign=top> + <td>Dimension Maximum #n (<size> bytes)</td> + <td>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + value <UNLIMITED> (all bits set) which indicates + that the data may expand along this dimension + indefinitely. If these values are not stored, the maximum + value of each dimension is assumed to be the same as the + current size value.</td> + </tr> + + <tr valign=top> + <td>Permutation Index #n (4 bytes)</td> + <td>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. If these values are + not stored, the first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension.</td> + </tr> + </table> + </center> + +<!-- Delete examples throughout doc + <h4>Examples</h4> + <dl> + <dt> Example #1 + <dd>A sample 640 horizontally by 480 vertically raster image + dimension header. The number of dimensions would be set to 2 + and the first dimension's size and maximum would both be set + to 480. The second dimension's size and maximum would both be + set to 640 +. + <dt>Example #2 + <dd>A sample 4 dimensional scientific dataset which is composed + of 30x24x3 slabs of data being written out in an unlimited + series every several minutes as timestep data (currently there + are five slabs). The number of dimensions is 4. The first + dimension size is 5 and its maximum is <UNLIMITED>. The + second through fourth dimension's size and maximum value are + set to 3, 24, and 30 respectively. + + <dt>Example #3 + <dd>A sample unlimited length text string, currently of length + 83. The number of dimensions is 1, the size of the first + dimension is 83 and the maximum of the first dimension is set + to <UNLIMITED>, allowing further text data to be + appended to the string or possibly the string to be replaced + with another string of a different size. (This could also be + stored as a scalar dataset with number-type set to "string") + </dl> +--> + +<!-- DELETE ENTIRE DATASPACE SECTION --> +<!-- + <hr> + <h4><a name="DataSpaceMessage">Name: Complex Dataspace (Fiber Bundle?)</a></h4> + <b>Type: </b>0x0002<br> + <b>Length:</b> varies<br> + + <b>Status:</b> One of the <em>Simple Dataspace</em> or + <em>Complex Dataspace</em> messages is required (but not both) and may + not be repeated.<br> <b>Purpose and Description:</b> The + <em>Dataspace</em> message describes space that the dataset is + mapped onto in a more comprehensive way than the <em>Simple + Dimensionality</em> message is capable of handling. The + dataspace of a dataset encompasses the type of coordinate system + used to locate the dataset's elements as well as the structure and + regularity of the coordinate system. The dataspace also + describes the number of dimensions which the dataset inhabits as + well as a possible higher dimensional space in which the dataset + is located within. + + <br> + <b>Format of Data:</b> + + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Message Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Mesh Type</td> + <tr align=center> + <td colspan=4>Logical Dimensionality</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br> + The mesh type value is broken up as follows: <br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Mesh-type Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=1>Mesh Embedding</td> + <td colspan=1>Coordinate System</td> + <td colspan=1>Structure</td> + <td colspan=1>Regularity</td> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset dataspace + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset's dataspace is located within + another dataspace, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric datatype. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed: + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + dataspace. + <br> <br> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Embedded Dimensionality Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Embedded Dimensionality</td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #n</td> + <tr align=center> + <td colspan=4>Embedded Origin Location #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Origin Location #n</td> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located + within. i.e. a planar dataset located within a 3-D space, + or a 3-D dataset + which is a subset of another 3-D space, etc. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded dataspace + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset's + origin within the embedded dataspace. + </dl> + </dl> + [Comment: need some way to handle different orientations of the + dataset dataspace + within the embedded dataspace]<br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Structured/Regular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Logical Dimension Size #1</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Logical Dimension Size #n</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #n</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> + </dl> + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Structured/Irregular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4># of Grid Points in Dimension #n</td> + <tr align=center> + <td colspan=4>Datatype of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #n</td> + </table> + </center> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Unstructured Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points</td> + <tr align=center> + <td colspan=4>Datatype of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Grid Point Locations<br>.<br>.<br></td> + </table> + </center> + + <h4><a name="DataSpaceExample">Examples:</a></h4> + Need some good examples, this is complex! +--> + + + <hr> + <h4><a name="DataTypeMessage">Name: Datatype</a></h4> + + <b>Type:</b> 0x0003<br> + <b>Length:</b> variable<br> + <b>Status:</b> One required per dataset or named datatype<br> + + <p>The datatype message defines the datatype for each data point + of a dataset. A datatype can describe an atomic type like a + fixed- or floating-point type or a compound type like a C + struct. A datatype does not, however, describe how data points + are combined to produce a dataset. Datatypes are stored on disk + as a datatype message, which is a list of datatype classes and + their associated properties. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Datatype Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Type Class and Version</td> + <td colspan=3>Class Bit Field</td> + </tr> + + <tr align=center> + <td colspan=4>Size in Bytes (4 bytes)</td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Properties<br><br><br></td> + </tr> + </table> + </center> + + <p>The Class Bit Field and Properties fields vary depending + on the Type Class, which is the low-order four bits of the Type + Class and Version field (the high-order four bits are the + version, which should be set to the value one). The type class + is one of 0 (fixed-point number), 1 (floating-point number), + 2 (date and time), 3 (text string), 4 (bit field), 5 (opaque), + 6 (compound), 7 (reference), 8 (enumeration), or 9 (variable-length). + The Class Bit Field is zero and the size of the + Properties field is zero except for the cases noted here. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Fixed-point Numbers (Class 0)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr valign=top> + <td>1, 2</td> + <td><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</td> + </tr> + + <tr valign=top> + <td>3</td> + <td><b>Signed.</b> If this bit is set then the fixed-point + number is in 2's complement form.</td> + </tr> + + <tr valign=top> + <td>4-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Fixed-point Numbers (Class 0)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Floating-point Numbers (Class 1)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr valign=top> + <td>1, 2, 3</td> + <td><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 + is the high bits pad type, and bit 3 is the internal bits + pad type. If a datum has unused bits at either or between + the sign bit, exponent, or mantissa, then the value of bit + 1, 2, or 3 is copied to those locations.</td> + </tr> + + <tr valign=top> + <td>4-5</td> + <td><b>Normalization.</b> The value can be 0 if there is no + normalization, 1 if the most significant bit of the + mantissa is always set (except for 0.0), and 2 if the most + signficant bit of the mantissa is not stored but is + implied to be set. The value 3 is reserved and will not + appear in this field.</td> + </tr> + + <tr valign=top> + <td>6-7</td> + <td>Reserved (zero).</td> + </tr> + + <tr valign=top> + <td>8-15</td> + <td><b>Sign.</b> This is the bit position of the sign + bit.</td> + </tr> + + <tr valign=top> + <td>16-23</td> + <td>Reserved (zero).</td> + </tr> + + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Floating-point Numbers (Class 1)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + + <tr align=center> + <td>Exponent Location</td> + <td>Exponent Size in Bits</td> + <td>Mantissa Location</td> + <td>Mantissa Size in Bits</td> + </tr> + + <tr align=center> + <td colspan=4>Exponent Bias</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Strings (Class 3)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0-3</td> + <td><b>Padding type.</b> This four-bit value determines the + type of padding to use for the string. The values are: + + <dl> + <dt><code>0</code> Null terminate. + <dd>A zero byte marks the end of the string and is + guaranteed to be present after converting a long + string to a short string. When converting a short + string to a long string the value is padded with + additional null characters as necessary. + + <br><br> + <dt><code>1</code> Null pad. + <dd>Null characters are added to the end of the value + during conversions from short values to long values + but conversion in the opposite direction simply + truncates the value. + + <br><br> + <dt><code>2</code> Space pad. + <dd>Space characters are added to the end of the value + during conversions from short values to long values + but conversion in the opposite direction simply + truncates the value. This is the Fortran + representation of the string. + + <br><br> + <dt><code>3-15</code> Reserved. + <dd>These values are reserved for future use. + </dl> + </tr> + + <tr valign=top> + <td>4-7</td> + <td><b>Character Set.</b> The character set to use for + encoding the string. The only character set supported is + the 8-bit ASCII (zero) so no translations have been defined + yet.</td> + </tr> + + <tr valign=top> + <td>8-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Bitfield Types (Class 4)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr valign=top> + <td>1, 2</td> + <td><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</td> + </tr> + + <tr valign=top> + <td>3-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Bitfield Types (Class 4)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Opaque Types (Class 5)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Opaque Types (Class 5)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Null-terminated ASCII Tag<br> + (multiple of 8 bytes)<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Compound Types (Class 6)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0-15</td> + <td><b>Number of Members.</b> This field contains the number + of members defined for the compound datatype. The member + definitions are listed in the Properties field of the data + type message. + </tr> + + <tr valign=top> + <td>15-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p>The Properties field of a compound datatype is a list of the + member definitions of the compound datatype. The member + definitions appear one after another with no intervening bytes. + The member types are described with a recursive datatype + message. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Compound Types (Class 6)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=4><br><br>Name (null terminated, multiple of + eight bytes)<br><br><br></td> + </tr> + + <tr align=center> + <td colspan=4>Byte Offset of Member in Compound Instance</td> + </tr> + + <tr align=center> + <td>Dimensionality</td> + <td colspan=3>reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension Permutation</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 0 (required)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 1 (required)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 2 (required)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 3 (required)</td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Member Type Message<br><br><br></td> + </tr> + + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Enumeration Types (Class 8)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0-15</td> + <td><b>Number of Members.</b> The number of name/value + pairs defined for the enumeration type.</td> + </tr> + + <tr valign=top> + <td>16-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Enumeration Types (Class 8)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Parent Type<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Names<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Values<br><br></td> + </tr> + + </table> + </center> + + <center> + <table border=0 cellpadding=4 width="80%"> + <tr align=left valign=top> + <td valign=top width=20%>Parent Type:</td> + <td valign=top>Each enumeration type is based on some parent type, + usually an integer. The information for that parent type is + described recursively by this field.</td> + </tr><tr align=left valign=top> + <td valign=top>Names:</td> + <td valign=top>The name for each name/value pair. Each name is + stored as a null terminated ASCII string in a multiple of + eight bytes. The names are in no particular order.</td> + </tr><tr align=left valign=top> + <td valign=top>Values:</td> + <td valign=top>The list of values in the same order as the names. + The values are packed (no inter-value padding) and the + size of each value is determined by the parent type.</td> + </tr> + </table> + </center> + + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Variable-length Types (Class 9)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr valign=top> + <td>0-3</td> + <td><dl><dt><b>Type</b></dt> + <dt>0 Variable-length sequence</dt> + <dd>This variable-length datatype can be of any sequence + of data. Variable-length sequences do not have padding + or character set information.</dd> + <dt>1 Variable-length string</dt> + <dd>This variable-length datatype is composed of a series of + characters. Variable-length strings have padding and + character set information.</dd></dl> + </td> + </tr> + + <tr valign=top> + <td>4-7</td> + <td><dl><dt><b>Padding type</b> (variable-length string only)</dt> + <dd>This four-bit value determines the type of padding + used for variable-length strings. The values are the same + as for the string padding type, as follows:</dd> + <dt>0 Null terminate</dt> + <dd>A zero byte marks the end of a string and is guaranteed + to be present after converting a long string to a short + string. When converting a short string to a long string, + the value is padded with additional null characters + as necessary. + <dt>1 Null pad</dt> + <dd>Null characters are added to the end of the value + during conversion from a short string to a longer string. + Conversion from a long string to a shorter string + simply truncates the value.</dd> + <dt>2 Space pad</dt> + <dd>Space characters are added to the end of the value + during conversion from a short string to a longer string. + Conversion from a long string to a shorter string simply + truncates the value. + This is the Fortran representation of the string. + </dd> + <dt>3-15 Reserved</dt> + <dd>These values are reserved for future use.</dd></dl> + </td> + </tr> + + <tr valign=top> + <td>8-11</td> + <td><dl><dt><b>Character set</b> (variable-length string only)</dt> + <dd>This four-bit value specifies the character set + to be used for encoding the string.</dd> + <dt>0 8-bit ASCII</dt> + <dd>As of this writing (July 2002, Release 1.4.4), + 8-bit ASCII is the only character set supported. + Therefore, no translations have been defined.</dd></dl> + </td> + </tr> + + <tr valign=top> + <td>12-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Variable-length Types (Class 9)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Parent Type<br><br></td> + </tr> + + </table> + </center> + + <center> + <table border=0 cellpadding=4 width="80%"> + <tr align=left valign=top> + <td valign=top width=20%>Parent Type:</td> + <td valign=top>Each variable-length type is based on + some parent type. The information for that parent type is + described recursively by this field.</td> + </tr> + </table> + </center> + + + + <p> + +<!-- + <p>Datatype examples are <a href="Datatypes.html">here</a>. +--> + + + <hr> + <h4><a name="FillValueMessage">Name: Data Storage - Fill Value</a></h4> + <b>Type:</b> 0x0004<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may not be repeated.<br> + + <p>The fill value message stores a single data point value which + is returned to the application when an uninitialized data point + is read from the dataset. The fill value is interpretted with + the same datatype as the dataset. If no fill value message is + present then a fill value of all zero is assumed. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Fill Value Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Size (4 bytes)</td> + </tr> + + <tr align=center> + <td colspan=4><br>Fill Value<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Size (4 bytes)</td> + <td>This is the size of the Fill Value field in bytes.</td> + </tr> + + <tr valign=top> + <td>Fill Value</td> + <td>The fill value. The bytes of the fill value are + interpreted using the same datatype as for the dataset.</td> + </tr> + </table> + </center> + + <hr> + <h4><a name="ReservedMessage_0005">Name: Reserved - Not Assigned Yet</a></h4> + <b>Type:</b> 0x0005<br> + <b>Length:</b> N/A<br> + <b>Status:</b> N/A<br> + + + + <hr> + <h4><a name="CompactDataStorageMessage">Name: Data Storage - Compact</a></h4> + + <b>Type:</b> 0x0006<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may not be repeated.<br> + + <p>This message indicates that the data for the data object is + stored within the current HDF file by including the actual + data as the header data for this message. The data is + stored internally in + the <em>normal format</em>, i.e. in one chunk, uncompressed, etc. + + <P>Note that one and only one of the <em>Data Storage</em> headers can be + stored for each data object. + + <P><b>Format of Data:</b> The message data is actually composed + of dataset data, so the format will be determined by the dataset + format. + +<!-- Delete examples throughout doc + <h4><a name="CompactDataStorageExample">Examples:</a></h4> + [very straightforward] +--> + + <hr> + <h4><a name="ExternalFileListMessage">Name: Data Storage - + External Data Files</a></h4> + <b>Type:</b> 0x0007<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may not be repeated.<BR> + + <p><b>Purpose and Description:</b> The external object message + indicates that the data for an object is stored outside the HDF5 + file. The filename of the object is stored as a Universal + Resource Location (URL) of the actual filename containing the + data. An external file list record also contains the byte offset + of the start of the data within the file and the amount of space + reserved in the file for that data. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>External File List Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td colspan=3>Reserved</td> + </tr> + + <tr align=center> + <td colspan=2>Allocated Slots</td> + <td colspan=2>Used Slots</td> + </tr> + + <tr align=center> + <td colspan=4><br>Heap Address<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Slot Definitions...<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version </td> + <td>This value is used to determine the format of the + External File List Message. When the format of the + information in the message is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>This field is reserved for future use.</td> + </tr> + + <tr valign=top> + <td>Allocated Slots</td> + <td>The total number of slots allocated in the message. Its + value must be at least as large as the value contained in + the Used Slots field.</td> + </tr> + + <tr valign=top> + <td>Used Slots</td> + <td>The number of initial slots which contain valid + information. The remaining slots are zero filled.</td> + </tr> + + <tr valign=top> + <td>Heap Address</td> + <td>This is the address of a local name heap which contains + the names for the external files. The name at offset zero + in the heap is always the empty string.</td> + </tr> + + <tr valign=top> + <td>Slot Definitions</td> + <td>The slot definitions are stored in order according to + the array addresses they represent. If more slots have + been allocated than what has been used then the defined + slots are all at the beginning of the list.</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>External File List Slot</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Name Offset (<size> bytes)<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>File Offset (<size> bytes)<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Size<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Name Offset (<size> bytes)</td> + <td>The byte offset within the local name heap for the name + of the file. File names are stored as a URL which has a + protocol name, a host name, a port number, and a file + name: + <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. + If the protocol is omitted then "file:" is assumed. If + the port number is omitted then a default port for that + protocol is used. If both the protocol and the port + number are omitted then the colon can also be omitted. If + the double slash and host name are omitted then + "localhost" is assumed. The file name is the only + mandatory part, and if the leading slash is missing then + it is relative to the application's current working + directory (the use of relative names is not + recommended).</td> + </tr> + + <tr valign=top> + <td>File Offset (<size> bytes)</td> + <td>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single + dataset this will usually be zero.</td> + </tr> + + <tr valign=top> + <td>Size</td> + <td>This is the total number of bytes reserved in the + specified file for raw data storage. For a file that + contains exactly one complete dataset which is not + extendable, the size will usually be the exact size of the + dataset. However, by making the size larger one allows + HDF5 to extend the dataset. The size can be set to a value + larger than the entire file since HDF5 will read zeros + past the end of the file without failing.</td> + </tr> + </table> + </center> + + + <hr> + <h4><a name="LayoutMessage">Name: Data Storage - Layout</a></h4> + + <b>Type:</b> 0x0008<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Required for datasets, may not be repeated. + + <p><b>Purpose and Description:</b> Data layout describes how the + elements of a multi-dimensional array are arranged in the linear + address space of the file. Two types of data layout are + supported: + + <ol> + <li>The array can be stored in one contiguous area of the file. + The layout requires that the size of the array be constant and + does not permit chunking, compression, checksums, encryption, + etc. The message stores the total size of the array and the + offset of an element from the beginning of the storage area is + computed as in C. + + <li>The array domain can be regularly decomposed into chunks and + each chunk is allocated separately. This layout supports + arbitrary element traversals, compression, encryption, and + checksums, and the chunks can be distributed across external + raw data files (these features are described in other + messages). The message stores the size of a chunk instead of + the size of the entire array; the size of the entire array can + be calculated by traversing the B-tree that stores the chunk + addresses. + </ol> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Data Layout Message</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td>Dimensionality</td> + <td>Layout Class</td> + <td>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4><br>Address<br><br></td> + </tr> + + <tr align=center> + <td colspan=4>Dimension 0 (4-bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension 1 (4-bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>...</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version</td> + <td>A version number for the layout message. This + documentation describes version one.</td> + </tr> + + <tr valign=top> + <td>Dimensionality</td> + <td>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the + message.</td> + </tr> + + <tr valign=top> + <td>Layout Class</td> + <td>The layout class specifies how the other fields of the + layout message are to be interpreted. A value of one + indicates contiguous storage while a value of two + indicates chunked storage. Other values will be defined + in the future.</td> + </tr> + + <tr valign=top> + <td>Address</td> + <td>For contiguous storage, this is the address of the first + byte of storage. For chunked storage this is the address + of the B-tree that is used to look up the addresses of the + chunks.</td> + </tr> + + <tr valign=top> + <td>Dimensions</td> + <td>For contiguous storage the dimensions define the entire + size of the array while for chunked storage they define + the size of a single chunk.</td> + </tr> + </table> + </center> + + + <hr> + <h4><a name="ReservedMessage_0009">Name: Reserved - Not Assigned Yet</a></h4> + <b>Type:</b> 0x0009<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + <b>Purpose and Description:</b> N/A<BR> + <b>Format of Data:</b> N/A + + <hr> + <h4><a name="ReservedMessage_000A">Name: Reserved - Not Assigned Yet</a></h4> + <b>Type:</b> 0x000A<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + <b>Purpose and Description:</b> N/A<BR> + <b>Format of Data:</b> N/A + + <hr> + <h4><a name="FilterMessage">Name: Data Storage - Filter Pipeline</a></h4> + <b>Type:</b> 0x000B<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may not be repeated. + + <p><b>Purpose and Description:</b> This message describes the + filter pipeline which should be applied to the data stream by + providing filter identification numbers, flags, a name, an + client data. + + <p> + <center> + <table border align=center cellpadding=4 witdh="80%"> + <caption align=top> + <b>Filter Pipeline Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td>Number of Filters</td> + <td colspan=2>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4><br>Filter List<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version</td> + <td>The version number for this message. This document + describes version one.</td> + </tr> + + <tr valign=top> + <td>Number of Filters</td> + <td>The total number of filters described by this + message. The maximum possible number of filters in a + message is 32.</td> + </tr> + + <tr valign=top> + <td>Filter List</td> + <td>A description of each filter. A filter description + appears in the next table.</td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center cellpadding=4 witdh="80%"> + <caption align=top> + <b>Filter Pipeline Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=2>Filter Identification</td> + <td colspan=2>Name Length</td> + </tr> + + <tr align=center> + <td colspan=2>Flags</td> + <td colspan=2>Client Data Number of Values</td> + </tr> + + <tr align=center> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Client Data<br><br></td> + </tr> + + <tr align=center> + <td colspan=4>Padding</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Filter Identification</td> + <td>This is a unique (except in the case of testing) + identifier for the filter. Values from zero through 255 + are reserved for filters defined by the NCSA HDF5 + library. Values 256 through 511 have been set aside for + use when developing/testing new filters. The remaining + values are allocated to specific filters by contacting the + <a href="mailto:hdf5dev@ncsa.uiuc.edu">HDF5 Development + Team</a>.</td> + </tr> + + <tr valign=top> + <td>Name Length</td> + <td>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>The flags indicate certain properties for a filter. The + bit values defined so far are: + + <dl> + <dt><code>bit 1</code> + <dd>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently removed from the pipeline. + </dl> + </tr> + + <tr valign=top> + <td>Client Data Number of Values</td> + <td>Each filter can store a few integer values to control + how the filter operates. The number of entries in the + Client Data array is stored in this field.</td> + </tr> + + <tr valign=top> + <td>Name</td> + <td>If the Name Length field is non-zero then it will + contain the size of this field, a multiple of eight. This + field contains a null-terminated, ASCII character + string to serve as a comment/name for the filter.</td> + </tr> + + <tr valign=top> + <td>Client Data</td> + <td>This is an array of four-byte integers which will be + passed to the filter function. The Client Data Number of + Values determines the number of elements in the + array.</td> + </tr> + + <tr valign=top> + <td>Padding</td> + <td>Four bytes of zeros are added to the message at this + point if the Client Data Number of Values field contains + an odd number.</td> + </tr> + </table> + </center> + + <hr> + <h4><a name="AttributeMessage">Name: Attribute</a></h4> + <b>Type:</b> 0x000C<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may be repeated.<BR> + + <p><b>Purpose and Description:</b> The <em>Attribute</em> + message is used to list objects in the HDF file which are used + as attributes, or "meta-data" about the current object. An + attribute is a small dataset; it has a name, a datatype, a data + space, and raw data. Since attributes are stored in the object + header they must be relatively small (<64kb) and can be + associated with any type of object which has an object header + (groups, datasets, named types and spaces, etc.). + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <b>Attribute Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Version</td> + <td>Reserved</td> + <td colspan=2>Name Size</td> + </tr> + + <tr align=center> + <td colspan=2>Type Size</td> + <td colspan=2>Space Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Type<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Space<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Data<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version</td> + <td>Version number for the message. This document describes + version 1 of attribute messages.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>This field is reserved for later use and is set to + zero.</td> + </tr> + + <tr valign=top> + <td>Name Size</td> + <td>The length of the attribute name in bytes including the + null terminator. Note that the Name field below may + contain additional padding not represented by this + field.</td> + </tr> + + <tr valign=top> + <td>Type Size</td> + <td>The length of the datatype description in the Type + field below. Note that the Type field may contain + additional padding not represented by this field.</td> + </tr> + + <tr valign=top> + <td>Space Size</td> + <td>The length of the dataspace description in the Space + field below. Note that the Space field may contain + additional padding not represented by this field.</td> + </tr> + + <tr valign=top> + <td>Name</td> + <td>The null-terminated attribute name. This field is + padded with additional null characters to make it a + multiple of eight bytes.</td> + </tr> + + <tr valign=top> + <td>Type</td> + <td>The datatype description follows the same format as + described for the datatype object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</td> + </tr> + + <tr valign=top> + <td>Space</td> + <td>The dataspace description follows the same format as + described for the dataspace object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</td> + </tr> + + <tr valign=top> + <td>Data</td> + <td>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. This + field is <em>not</em> padded with additional zero + bytes.</td> + </tr> + </table> + </center> + + <hr> + <h4><a name="NameMessage">Name: Object Name</a></h4> + + <p><b>Type:</b> 0x000D<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may not be repeated. + + <p><b>Purpose and Description:</b> The object name or comment is + designed to be a short description of an object. An object name + is a sequence of non-zero (<code>\0</code>) ASCII characters with no other + formatting included by the library. + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <b>Name Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Name<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Name</td> + <td>A null terminated ASCII character string.</td> + </tr> + </table> + </center> + + <hr> + <h4><a name="ModifiedMessage">Name: Object Modification Date & Time</a></h4> + + <p><b>Type:</b> 0x000E<br> + <b>Length:</b> fixed<br> + <b>Status:</b> Optional, may not be repeated. + + <p><b>Purpose and Description:</b> The object modification date + and time is a timestamp which indicates (using ISO-8601 date and + time format) the last modification of an object. The time is + updated when any object header message changes according to the + system clock where the change was posted. + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <b>Modification Time Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Year</td> + </tr> + + <tr align=center> + <td colspan=2>Month</td> + <td colspan=2>Day of Month</td> + </tr> + + <tr align=center> + <td colspan=2>Hour</td> + <td colspan=2>Minute</td> + </tr> + + <tr align=center> + <td colspan=2>Second</td> + <td colspan=2>Reserved</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Year</td> + <td>The four-digit year as an ASCII string. For example, + <code>1998</code>. All fields of this message should be interpreted + as coordinated universal time (UTC)</td> + </tr> + + <tr valign=top> + <td>Month</td> + <td>The month number as a two digit ASCII string where + January is <code>01</code> and December is <code>12</code>.</td> + </tr> + + <tr valign=top> + <td>Day of Month</td> + <td>The day number within the month as a two digit ASCII + string. The first day of the month is <code>01</code>.</td> + </tr> + + <tr valign=top> + <td>Hour</td> + <td>The hour of the day as a two digit ASCII string where + midnight is <code>00</code> and 11:00pm is <code>23</code>.</td> + </tr> + + <tr valign=top> + <td>Minute</td> + <td>The minute of the hour as a two digit ASCII string where + the first minute of the hour is <code>00</code> and + the last is <code>59</code>.</td> + </tr> + + <tr valign=top> + <td>Second</td> + <td>The second of the minute as a two digit ASCII string + where the first second of the minute is <code>00</code> + and the last is <code>59</code>.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>This field is reserved and should always be zero.</td> + </tr> + </table> + </center> + + <hr> + <h4><a name="SharedMessage">Name: Shared Object Message</a></h4> + <b>Type:</b> 0x000F<br> + <b>Length:</b> 4 Bytes<br> + <b>Status:</b> Optional, may be repeated. + + <p>A constant message can be shared among several object headers + by writing that message in the global heap and having the object + headers all point to it. The pointing is accomplished with a + Shared Object message which is understood directly by the object + header layer of the library. It is also possible to have a + message of one object header point to a message in some other + object header, but care must be exercised to prevent cycles. + + <p>If a message is shared, then the message appears in the global + heap and its message ID appears in the Header Message Type + field of the object header. Also, the Flags field in the object + header for that message will have bit two set (the + <code>H5O_FLAG_SHARED</code> bit). The message body in the + object header will be that of a Shared Object message defined + here and not that of the pointed-to message. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Shared Message Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + </tr> + + <tr align=center> + <td>Version</td> + <td>Flags</td> + <td colspan=2>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4><br>Pointer<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version</td> + <td>The version number for the message. This document + describes version one of shared messages.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>The Shared Message message points to a message which is + shared among multiple object headers. The Flags field + describes the type of sharing: + + <dl> + <dt><code>Bit 0</code> + <dd>If this bit is clear then the actual message is the + first message in some other object header; otherwise + the actual message is stored in the global heap. + + <dt><code>Bits 2-7</code> + <dd>Reserved (always zero) + </dl> + </tr> + + <tr valign=top> + <td>Pointer</td> + <td>This field points to the actual message. The format of + the pointer depends on the value of the Flags field. If + the actual message is in the global heap then the pointer + is the file address of the global heap collection that + holds the message, and a four-byte index into that + collection. Otherwise the pointer is a group entry + that points to some other object header.</td> + </tr> + </table> + </center> + + +<hr> +<h4><a name="ContinuationMessage">Name: Object Header Continuation</a></h4> +<b>Type:</b> 0x0010<BR> +<b>Length:</b> fixed<BR> +<b>Status:</b> Optional, may be repeated.<BR> +<b>Purpose and Description:</b> The object header continuation is the location +in the file of more header messages for the current data object. This can be +used when header blocks are large, or likely to change over time.<BR> +<b>Format of Data:</b><p> + The object header continuation is formatted as follows (assuming a 4-byte +length & offset are being used in the current file): + +<P> +<center> +<table border cellpadding=4 width=60%> +<caption align=bottom> +<B>HDF5 Object Header Continuation Message Layout</B> +</caption> + +<tr align=center> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> + +<tr align=center> +<td colspan=4>Header Continuation Offset</td> +<tr align=center> +<td colspan=4>Header Continuation Length</td> +</table> +</center> + +<P> +<dl> +<dt>The elements of the Header Continuation Message are described below: +<dd> +<dl> +<dt>Header Continuation Offset: (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file where the +header continuation information is located. +<dt>Header Continuation Length: (<length> bytes) +<dd>This value is the length in bytes of the header continuation information in +the file. +</dl> +</dl> + +<!-- Delete examples throughout doc +<h4><a name="ContinuationExample">Examples:</a></h4> + [straightforward] +--> + +<hr> +<h4><a name="SymbolTableMessage">Name: Group Message</a></h4> +<b>Type:</b> 0x0011<BR> +<b>Length:</b> fixed<BR> +<b>Status:</b> Required for groups, may not be repeated.<BR> +<b>Purpose and Description:</b> Each group has a B-tree and a +name heap which are pointed to by this message.<BR> +<b>Format of data:</b> +<p>The group message is formatted as follows: + +<p> +<center> +<table border cellpadding=4 width="80%"> +<caption align=bottom> +<b>HDF5 Object Header Group Message Layout</b> +</caption> + +<tr align=center> +<th width="25%">byte</th> +<th width="25%">byte</th> +<th width="25%">byte</th> +<th width="25%">byte</th> + +<tr align=center> +<td colspan=4>B-tree Address</td> + +<tr align=center> +<td colspan=4>Heap Address</td> +</table> +</center> + +<P> +<dl> +<dt>The elements of the Group Message are described below: +<dd> +<dl> +<dt>B-tree Address (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file +where the B-tree is located. +<dt>Heap Address (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file +where the group name heap is located. +</dl> +</dl> + +<h3><a name="SharedObjectHeader">Disk Format: Level 2b - Shared Data Object Headers</a></h3> +<P>In order to share header messages between several dataset objects, object +header messages may be placed into the global heap. Since these +messages require additional information beyond the basic object header message +information, the format of the shared message is detailed below. + +<BR> <BR> +<center> +<table border cellpadding=4 width=60%> +<caption align=bottom> +<B>HDF5 Shared Object Header Message</B> +</caption> + +<tr align=center> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> + +<tr align=center> +<td colspan=4>Reference Count of Shared Header Message</td> +<tr align=center> +<td colspan=4><br> Shared Object Header Message<br> <br></td> +</table> +</center> + +<p> +<dl> +<dt> The elements of the shared object header message are described below: +<dd> +<dl> +<dt>Reference Count of Shared Header Message: (32-bit unsigned integer) +<dd>This value is used to keep a count of the number of dataset objects which +refer to this message from their dataset headers. When this count reaches zero, +the shared message header may be removed from the global heap. +<dt>Shared Object Header Message: (various lengths) +<dd>The data stored for the shared object header message is formatted in the +same way as the private object header messages described in the object header +description earlier in this document and begins with the header message Type. +</dl> +</dl> + + +<h3><a name="DataStorage">Disk Format: Level 2c - Data Object Data Storage</a></h3> +<P>The data for an object is stored separately from the header +information in the file and may not actually be located in the HDF5 file +itself if the header indicates that the data is stored externally. The +information for each record in the object is stored according to the +dimensionality of the object (indicated in the dimensionality header message). +Multi-dimensional data is stored in C order [same as current scheme], i.e. the +"last" dimension changes fastest. +<P>Data whose elements are composed of simple number-types are stored in +native-endian IEEE format, unless they are specifically defined as being stored +in a different machine format with the architecture-type information from the +number-type header message. This means that each architecture will need to +[potentially] byte-swap data values into the internal representation for that +particular machine. +<P> Data with a "variable" sized number-type is stored in a data heap +internal to the HDF5 file. Global heap identifiers are stored in the +data object storage. +<P>Data whose elements are composed of pointer number-types are stored in several +different ways depending on the particular pointer type involved. Simple +pointers are just stored as the dataset offset of the object being pointed to with the +size of the pointer being the same number of bytes as offsets in the file. +Partial-object pointers are stored as a heap-ID which points to the following +information within the file-heap: an offset of the object pointed to, number-type +information (same format as header message), dimensionality information (same +format as header message), sub-set start and end information (i.e. a coordinate +location for each), and field start and end names (i.e. a [pointer to the] +string indicating the first field included and a [pointer to the] string name +for the last field). + +<P>Data of a compound datatype is stored as a contiguous stream of the items +in the structure, with each item formatted according to its datatype. + +</body> +</html> diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html new file mode 100644 index 0000000..ebbbe8e --- /dev/null +++ b/doxygen/examples/H5.format.1.1.html @@ -0,0 +1,6439 @@ +<html> + <head> + <title> + HDF5 File Format Specification Version 1.1 + </title> + +<STYLE TYPE="text/css"> + +P { text-indent: 2em} +P.item { margin-left: 2em; text-indent: -2em} +P.item2 { margin-left: 2em; text-indent: 2em} + +TABLE.format { border:solid; border-collapse:collapse; caption-side:top; text-align:center; width:80%;} +TABLE.format TH { border:ridge; padding:4px; width:25%;} +TABLE.format TD { border:ridge; padding:4px; } +TABLE.format CAPTION { font-weight:bold; font-size:larger;} + +TABLE.note {border:none; text-align:right; width:80%;} + +TABLE.desc { border:solid; border-collapse:collapse; caption-size:top; text-align:left; width:80%;} +TABLE.desc TR { vertical-align:top;} +TABLE.desc TH { border-style:ridge; font-size:larger; padding:4px; text-decoration:underline;} +TABLE.desc TD { border-style:ridge; padding:4px; } +TABLE.desc CAPTION { font-weight:bold; font-size:larger;} + +TABLE.list { border:none; } +TABLE.list TR { vertical-align:top;} +TABLE.list TH { border:none; text-decoration:underline;} +TABLE.list TD { border:none; } + +</STYLE> +</head> + <body> + + <center> + <table border=0 width=90%> + <tr> + <td valign=top> + <ol type=I> + <li><a href="#Intro">Introduction</a> + <li><a href="#FileMetaData">Disk Format Level 0 - File Metadata</a> + <font size=-2> + <ol type=A> + <li><a href="#SuperBlock">Disk Format Level 0A - File Signature and Super Block</a> + <li><a href="#DriverInfo">Disk Format Level 0B - File Driver Info</a> + </ol> + </font> + <li><a href="#FileInfra">Disk Format Level 1 - File Infrastructure</a> + <font size=-2> + <ol type=A> + <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> + <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> + <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> + <li><a href="#LocalHeap">Disk Format Level 1D - Local Heaps</a> + <li><a href="#GlobalHeap">Disk Format Level 1E - Global Heap</a> + <li><a href="#FreeSpaceIndex">Disk Format Level 1F - Free-space Index</a> + </ol> + </font> + <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> + <font size=-2> + <ol type=A> + <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> + <ol type=1> + <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> + <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> +<!-- <li><a href="#DataSpaceMessage">Name: Complex Dataspace</a> --> <!-- 0x0002 --> + <li><a href="#ReservedMessage_0002">Name: Reserved - not assigned yet</a> <!-- 0x0002 --> + <li><a href="#DataTypeMessage">Name: Datatype</a> <!-- 0x0003 --> + <li><a href="#OldFillValueMessage">Name: Data Storage - Fill Value (Old)</a> <!-- 0x0004 --> + <li><a href="#FillValueMessage">Name: Data Storage - Fill Value</a> <!-- 0x0005 --> + </ol> + </ol> + </font> + </ol> + </td><td> </td><td valign=top> + <ol type=I start=4> + + <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> + <font size=-2><i>(Continued)</i> + <ol type=A> + <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> + <ol type=1 start=6> +<!-- <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> --> <!-- 0x0006 --> + <li><a href="#ReservedMessage_0006">Name: Reserved - not assigned yet</a> <!-- 0x0006 --> + <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> + <li><a href="#LayoutMessage">Name: Data Storage - Layout</a> <!-- 0x0008 --> + <li><a href="#ReservedMessage_0009">Name: Reserved - not assigned yet</a> <!-- 0x0009 --> + <li><a href="#ReservedMessage_000A">Name: Reserved - not assigned yet</a> <!-- 0x000a --> + <li><a href="#FilterMessage">Name: Data Storage - Filter Pipeline</a> <!-- 0x000b --> + <li><a href="#AttributeMessage">Name: Attribute</a> <!-- 0x000c --> + <li><a href="#CommentMessage">Name: Object Comment</a> <!-- 0x000d --> + <li><a href="#OldModifiedMessage">Name: Object Modification Date and Time (Old)</a> <!-- 0x000e --> + <li><a href="#SharedMessage">Name: Shared Object Message</a> <!-- 0x000f --> + <li><a href="#ContinuationMessage">Name: Object Header Continuation</a> <!-- 0x0010 --> + <li><a href="#SymbolTableMessage">Name: Group Message</a> <!-- 0x0011 --> + <li><a href="#ModifiedMessage">Name: Object Modification Date and Time</a> <!-- 0x0012 --> + </ol> + <li><a href="#DataStorage">Disk Format: Level 2b - Data Object Data Storage</a> + </ol> + </font> + <LI><A href="#Appendix">Appendix</A> + </ol> +</td></tr> +</table> +</center> + + <BR> + <HR> + + + <h2>Introduction</h2> + + <table align=right width=100> + <tr><td> </td><td align=center> + <hr> + <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace=15 vspace=15> + </td><td> </td></tr> + <tr><td> </td><td align=center> + <strong>Figure 1:</strong> Relationships among the HDF5 root group, other groups, and objects + <hr> + </td><td> </td></tr> + + <tr><td> </td><td align=center> + <img src="FF-IH_FileObject.gif" alt="HDF5 Objects" hspace=15 vspace=15> + </td><td> </td></tr> + <tr><td> </td><td align=center> + <strong>Figure 2:</strong> HDF5 objects -- datasets, datatypes, or dataspaces + <hr> + </td><td> </td></tr> + </table> + + + <P>The format of an HDF5 file on disk encompasses several + key ideas of the HDF4 and AIO file formats as well as + addressing some shortcomings therein. The new format is + more self-describing than the HDF4 format and is more + uniformly applied to data objects in the file. + + <P>An HDF5 file appears to the user as a directed graph. + The nodes of this graph are the higher-level HDF5 objects + that are exposed by the HDF5 APIs: + + <ul> + <li>Groups + <li>Datasets + <li>Named datatypes + </ul> + + <P>At the lowest level, as information is actually written to the disk, + an HDF5 file is made up of the following objects: + <ul> + <li>A super block + <li>B-tree nodes (containing either symbol nodes or raw data chunks) + <li>Object headers + <li>A global heap + <li>Local heaps + <li>Free space + </ul> + + <P>The HDF5 library uses these low-level objects to represent the + higher-level objects that are then presented to the user or + to applications through the APIs. + For instance, a group is an object header that contains a message that + points to a local heap and to a B-tree which points to symbol nodes. + A dataset is an object header that contains messages that describe + datatype, space, layout, filters, external files, fill value, etc + with the layout message pointing to either a raw data chunk or to a + B-tree that points to raw data chunks. + + + <h3>This Document</h3> + + <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>. + + <P>Three levels of information comprise the file format. + Level 0 contains basic information for identifying and + defining information about the file. Level 1 information contains + the information about the pieces of a file shared by many objects + in the file (such as a B-trees and heaps). Level 2 is the rest + of the file and contains all of the data objects, with each object + partitioned into header information, also known as + <em>metadata</em>, and data. + + <p>The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans + in the table. There are three exceptions: (1) The size may be + overridden by specifying a size in parentheses, (2) the size of + addresses is determined by the <em>Size of Offsets</em> field + in the super block and is indicated in this document with a + superscripted 'O', and (3) the size of length fields is determined + by the <em>Size of Lengths</em> field in the super block and is + indicated in this document with a superscripted 'L'. + + <P>Values for all fields in this document should be treated as unsigned + integers, unless otherwise noted in the description of a field. + Additionally, all metadata fields are stored in little-endian byte + order. + </P> + + <BR> + <HR> + + <h2><a name="FileMetaData"> + Disk Format: Level 0 - File Metadata</a></h2> + + <H3><A name="SuperBlock"> + Disk Format: Level 0A - File Signature and Super Block</A></H3> + + <P>The super block may begin at certain predefined offsets within + the HDF5 file, allowing a block of unspecified content for + users to place additional information at the beginning (and + end) of the HDF5 file without limiting the HDF5 library's + ability to manage the objects within the file itself. This + feature was designed to accommodate wrapping an HDF5 file in + another file format or adding descriptive information to the + file without requiring the modification of the actual file's + information. The super block is located by searching for the + HDF5 file signature at byte offset 0, byte offset 512 and at + successive locations in the file, each a multiple of two of + the previous location, i.e. 0, 512, 1024, 2048, etc. + + <P>The super block is composed of a file signature, followed by + super block and group version numbers, information + about the sizes of offset and length values used to describe + items within the file, the size of each group page, + and a group entry for the root object in the file. + + <br> + <div align=center> + <table class=format> + <caption> + HDF5 Super Block Layout + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=4><br>HDF5 File Signature (8 bytes)<br><br></td> + </tr> + + <tr> + <td>Version # of Super Block</td> + <td>Version # of Global Free-space Storage</td> + <td>Version # of Root Group Symbol Table Entry</td> + <td>Reserved (zero)</td> + </tr> + + <tr> + <td>Version # of Shared Header Message Format</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=2>Group Leaf Node K</td> + <td colspan=2>Group Internal Node K</td> + </tr> + + <tr> + <td colspan=4>File Consistency Flags</td> + </tr> + + <tr> + <td colspan=2 style="border:dotted;">Indexed Storage Internal Node K<sup>1</sup></td> + <td colspan=2 style="border:dotted;">Reserved (zero)<sup>1</sup></td> + </tr> + + <tr> + <td colspan=4>Base Address<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>Address of Global Free-space Heap<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>End of File Address<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>Driver Information Block Address<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>Root Group Symbol Table Entry</td> + </tr> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'O' the above table are + <br> + of the size specified in "Size of Offsets.") + </td></tr> + <tr><td> + (Items marked with an '1' the above table are + <br> + new in version 1 of the superblock) + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>HDF5 File Signature</td> + <td> + <P>This field contains a constant value and can be used to + quickly identify a file as being an HDF5 file. The + constant value is designed to allow easy identification of + an HDF5 file and to allow certain types of data corruption + to be detected. The file signature of an HDF5 file always + contains the following values: + </P> + + <center> + <table border align=center cellpadding=4> + <tr align=center> + <td align=right>Decimal:</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align=center> + <td align=right>Hexadecimal:</td> + <td>89</td> + <td>48</td> + <td>44</td> + <td>46</td> + <td>0d</td> + <td>0a</td> + <td>1a</td> + <td>0a</td> + </tr> + + <tr align=center> + <td align=right>ASCII C Notation:</td> + <td>\211</td> + <td>H</td> + <td>D</td> + <td>F</td> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + </table> + </center> + <br> + + <P>This signature both identifies the file as an HDF5 file + and provides for immediate detection of common + file-transfer problems. The first two bytes distinguish + HDF5 files on systems that expect the first two bytes to + identify the file type uniquely. The first byte is + chosen as a non-ASCII value to reduce the probability + that a text file may be misrecognized as an HDF5 file; + also, it catches bad file transfers that clear bit + 7. Bytes two through four name the format. The CR-LF + sequence catches bad file transfers that alter newline + sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse + of the CR-LF translation problem. (This is a direct + descendent of the <A href="http://www.libpng.org/pub/png/spec/PNG-Rationale.html#R.PNG-file-signature">PNG</A> file + signature.) + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Version Number of the Super Block</td> + <td> + <P>This value is used to determine the format of the + information in the super block. When the format of the + information in the super block is changed, the version number + is incremented to the next integer and can be used to + determine how the information in the super block is + formatted. + </P> + + <P>Values of 0 and 1 are defined for this field. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Version Number of the File Free-space Information</td> + <td> + <P>This value is used to determine the format of the + information in the File Free-space Information. + </P> + <P>The only value currently valid in this field is '0', which + indicates that the free space index is formatted as described + <A href="#FreeSpaceIndex">below</A>. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Version Number of the Root Group Symbol Table Entry</td> + <td> + <P>This value is used to determine the format of the + information in the Root Group Symbol Table Entry. When the + format of the information in that field is changed, the + version number is incremented to the next integer and can be + used to determine how the information in the field + is formatted. + </P> + <P>The only value currently valid in this field is '0', which + indicates that the root group symbol table entry is formatted as + described <A href="#SymbolTableEntry">below</A>. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Version Number of the Shared Header Message Format</td> + <td> + <P>This value is used to determine the format of the + information in a shared object header message. Since the format + of the shared header messages differs from the other private + header messages, a version number is used to identify changes + in the format. + </P> + <P>The only value currently valid in this field is '0', which + indicates that shared header messages are formatted as + described <A href="#SharedMessage">below</A>. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Size of Offsets</td> + <td> + <P>This value contains the number of bytes used to store + addresses in the file. The values for the addresses of + objects in the file are offsets relative to a base address, + usually the address of the super block signature. This + allows a wrapper to be added after the file is created + without invalidating the internal offset locations. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Size of Lengths</td> + <td> + <P>This value contains the number of bytes used to store + the size of an object. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Group Leaf Node K</td> + <td> + <P>Each leaf node of a group B-tree will have at + least this many entries but not more than twice this + many. If a group has a single leaf node then it + may have fewer entries. + </P> + <P>This value must be greater than zero. + </P> + <P>See the <A href="#Btrees">description</A> of B-trees below. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Group Internal Node K</td> + <td> + <P>Each internal node of a group B-tree will have at + least this many entries but not more than twice this + many. If the group has only one internal + node then it might have fewer entries. + </P> + <P>This value must be greater than zero. + </P> + <P>See the <A href="#Btrees">description</A> of B-trees below. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>File Consistency Flags</td> + <td> + <P>This value contains flags to indicate information + about the consistency of the information contained + within the file. Currently, the following bit flags are + defined: + <ul> + <li>Bit 0 set indicates that the file is opened for + write-access. + <li>Bit 1 set indicates that the file has + been verified for consistency and is guaranteed to be + consistent with the format defined in this document. + <li>Bits 2-31 are reserved for future use. + </ul> + Bit 0 should be + set as the first action when a file is opened for write + access and should be cleared only as the final action + when closing a file. Bit 1 should be cleared during + normal access to a file and only set after the file's + consistency is guaranteed by the library or a + consistency utility. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Indexed Storage Internal Node K</td> + <td> + <P>Each internal node of a indexed storage B-tree will have at + least this many entries but not more than twice this + many. If the group has only one internal + node then it might have fewer entries. + </P> + <P>This value must be greater than zero. + </P> + <P>See the <A href="#Btrees">description</A> of B-trees below. + </P> + + <P><EM>This field is present in version 1+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Base Address</td> + <td> + <P>This is the absolute file address of the first byte of + the HDF5 data within the file. The library currently + constrains this value to be the absolute file address + of the super block itself when creating new files; + future versions of the library may provide greater + flexibility. When opening an existing file and this address does + not match the offset of the superblock, the library assumes + that the entire contents of the HDF5 file have been adjusted in + the file and adjusts the base address and end of file address to + reflect their new positions in the file. Unless otherwise noted, + all other file addresses are relative to this base + address. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Address of Global Free-space Index</td> + <td> + <P>Free-space management is not yet defined in the HDF5 + file format and is not handled by the library. + Currently this field always contains the + <A href="#UndefinedAddress">undefined address</A>. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>End of File Address</td> + <td> + <P>This is the absolute file address of the first byte past + the end of all HDF5 data. It is used to determine whether a + file has been accidently truncated and as an address where + file data allocation can occur if space from the free list is + not used. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Driver Information Block Address</td> + <td> + <P>This is the relative file address of the file driver + information block which contains driver-specific + information needed to reopen the file. If there is no + driver information block then this entry should be the + <A href="#UndefinedAddress">undefined address</A>. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + + <tr> + <td>Root Group Symbol Table Entry</td> + <td> + <P>This is the <A href="#SymbolTableEntry">symbol table entry</A> + of the root group, which serves as the entry point into + the group graph for the file. + </P> + + <P><EM>This field is present in version 0+ of the superblock.</EM> + </P> + </td> + </tr> + </table> + </div> + + <H3><A name="DriverInfo"> + Disk Format: Level 0B - File Driver Info</A></H3> + + <p>The <em>file driver information block</em> is an optional region of the + file which contains information needed by the file driver in + order to reopen a file. The format of the file driver information + block is: + + <br> + <div align=center> + <table class=format> + <caption> + Driver Information Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Driver Information Size (4 bytes)</td> + </tr> + + <tr> + <td colspan=4><br>Driver Identification (8 bytes)<br><br></td> + </tr> + + <tr> + <td colspan=4><br><br>Driver Information (<em>n</em> bytes)<br><br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>The version number of the driver information block. The + file format documented here is version zero. + </P> + </td> + </tr> + + <tr> + <td>Driver Information Size</td> + <td> + <P>The size in bytes of the Driver Information part of this + structure. + </P> + </td> + </tr> + + <tr> + <td>Driver Identification</td> + <td> + <P>This is an eight-byte ASCII string without null + termination which identifies the driver and version number + of the Driver Information block. The predefined drivers + supplied with the HDF5 library are identified by the + letters <code>NCSA</code> followed by the first four characters of + the driver name. If the Driver Information block is not + the original version then the last letter(s) of the + identification will be replaced by a version number in + ASCII. + </P> + <P> + For example, the various versions of the <em>multi driver</em> + will be identified by <code>NCSAmult</code>. + (<code>NCSAmult</code> is simply <code>NCSAmulti</code> truncated + to eight characters. Subsequent identifiers will be created by + substituting sequential numerical values for the final character, + starting with zero.) <em>multi driver</em> is the only default driver that + is encoded in this field. + </P> + <P> + Identification for user-defined drivers + is eight-byte long and arbitrary but should be unique and avoid + the four character prefix "NCSA". + </P> + </td> + </tr> + + <tr valign=top> + <td>Driver Information</td> + <td>Driver information is encoded/decoded in a format defined by the + file driver. <em>multi driver</em> is the only default driver that has driver + information stored in this field. Its format is explained in the + following block.</td> + </tr> + </table> + </div> + + <BR> + <P><em>Multi driver</em> has the following format:</P> + + <div align=center> + <table class=format> + <caption> + Multi Driver Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Reserved</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan=4><br>Address of Member File 1<br><br></td> + </tr> + + <tr> + <td colspan=4><br>End of Address for Member File 1<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Address of Member File 2<br><br></td> + </tr> + + <tr> + <td colspan=4><br>End of Address for Member File 2<br><br></td> + </tr> + + <tr> + <td colspan=4><br>... ...<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Name of Member File 1<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Name of Member File 2<br><br></td> + </tr> + + <tr> + <td colspan=4><br>... ...<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Member Mapping</td> + <td><P><em>Multi driver</em> enables different types of HDF5 data and + metadata to be written to separate files. These files are viewed by the + library as a single virtual HDF5 file with a single file address. + It allows maximal 6 files to be created. + In sequence, these <em>Member Mapping</em> fields are for super block, + B-tree, raw data, global heap, local heap, + and object header. More than one type of data can be written to the + same file.</P> + <P>These <em>Member Mapping</em> fields are integer values from 1 to 6 + indicating how the data can be mapped to or merged with another type of + data. + <table class=list> + <tr> + <th width="30%">Member Mapping</th> + <th align=left>Description</th> + </tr> + <tr> + <td align=center>1</td> + <td>The super block data.</td> + </tr> + <tr> + <td align=center>2</td> + <td>The B-tree data.</td> + </tr> + <tr> + <td align=center>3</td> + <td>The raw data.</td> + </tr> + <tr> + <td align=center>4</td> + <td>The global heap data.</td> + </tr> + <tr> + <td align=center>5</td> + <td>The local heap data.</td> + </tr> + <tr> + <td align=center>6</td> + <td>The object header data.</td> + </tr> + </table></P> + For example, if the third field has the value 3 and all the rest have the + value 1, it means there are two files, one for raw data, one for super block, + B-tree, global heap, local heap, and object header. + </td> + </tr> + + <tr> + <td>Reserved</td> + <td><P>These fields are reserved and should always be zero.</P></td> + </tr> + + <tr> + <td>Address of Member File</td> + <td><P>Specifies the virtual address. A normally eight-byte integer with + the value from <em>0</em> (zero) to maximal value, + at which the member file starts.</P></td> + </tr> + + <tr> + <td>End of Address for Member File</td> + <td><P>The end of allocated address for the member file. A normally eight-byte + integer value.</P></td> + </tr> + + <tr> + <td>Name of Member File</td> + <td><P>The null-terminated name of member file. Its length should be multiples of + 8 bytes. Additional bytes will be padded with <em>NULL</em>s. The default naming + convention is <em>%%s-X.h5</em>, where <em>X</em> is one of the letters + <em>s</em> (for super block), <em>b</em> (for B-tree), <em>r</em> (for raw data), + <em>g</em> (for global heap), <em>l</em> (for local heap), and <em>o</em> (for + object header). The name for the whole HDF5 file will substitute the <em>%s</em> + in the string. + </P> + </td> + </tr> + </table> + </div> + + <BR> + <HR> + + <h2><a name="FileInfra"> + Disk Format: Level 1 - File Infrastructure</a></h2> + <h3><a name="Btrees">Disk Format: Level 1A - B-link Trees and B-tree Nodes</a></h3> + + <p>B-link trees allow flexible storage for objects which tend to grow + in ways that cause the object to be stored discontiguously. B-trees + are described in various algorithms books including "Introduction to + Algorithms" by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. The B-link tree, in which the sibling nodes at a + particular level in the tree are stored in a doubly-linked list, + is described in the "Efficient Locking for Concurrent Operations + on B-trees" paper by Phillip Lehman and S. Bing Yao as published + in the <cite>ACM Transactions on Database Systems</cite>, Vol. 6, + No. 4, December 1981. + + <p>The B-link trees implemented by the file format contain one more + key than the number of children. In other words, each child + pointer out of a B-tree node has a left key and a right key. + The pointers out of internal nodes point to sub-trees while + the pointers out of leaf nodes point to symbol nodes and + raw data chunks. + Aside from that difference, internal nodes and leaf nodes + are identical. + + <br> + <div align=center> + <table class=format> + <caption> + B-tree Nodes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + + <tr> + <td colspan=4>Signature</td> + + <tr> + <td>Node Type</td> + <td>Node Level</td> + <td colspan=2>Entries Used</td> + + <tr> + <td colspan=4>Address of Left Sibling<sup>O</sup></td> + + <tr> + <td colspan=4>Address of Right Sibling<sup>O</sup></td> + + <tr> + <td colspan=4>Key 0 (variable size)</td> + + <tr> + <td colspan=4>Address of Child 0<sup>O</sup></td> + + <tr> + <td colspan=4>Key 1 (variable size)</td> + + <tr> + <td colspan=4>Address of Child 1<sup>O</sup></td> + + <tr> + <td colspan=4>...</td> + + <tr> + <td colspan=4>Key 2<em>K</em> (variable size)</td> + + <tr> + <td colspan=4>Address of Child 2<em>K</em><sup>O</sup></td> + + <tr> + <td colspan=4>Key 2<em>K</em>+1 (variable size)</td> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'O' the above table are + <br> + of the size specified in "Size of Offsets.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Signature</td> + <td> + <P>The ASCII character string "<code>TREE</code>" is + used to indicate the + beginning of a B-link tree node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file. + </P> + </td> + </tr> + + <tr> + <td>Node Type</td> + <td> + <P>Each B-link tree points to a particular type of data. + This field indicates the type of data as well as + implying the maximum degree <em>K</em> of the tree and + the size of each Key field. + </P> + + <table class=list> + <tr> + <th width="30%">Node Type</th> + <th align=left>Description</th> + </tr> + <tr> + <td align=center>0</td> + <td>This tree points to group nodes.</td> + </tr> + <tr> + <td align=center>1</td> + <td>This tree points to raw data chunk nodes.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Node Level</td> + <td> + <P>The node level indicates the level at which this node + appears in the tree (leaf nodes are at level zero). Not + only does the level indicate whether child pointers + point to sub-trees or to data, but it can also be used + to help file consistency checking utilities reconstruct + damanged trees. + </P> + </td> + </tr> + + <tr valign=top> + <td>Entries Used</td> + <td> + <P>This determines the number of children to which this + node points. All nodes of a particular type of tree + have the same maximum degree, but most nodes will point + to less than that number of children. The valid child + pointers and keys appear at the beginning of the node + and the unused pointers and keys appear at the end of + the node. The unused pointers and keys have undefined + values. + </P> + </td> + </tr> + + <tr valign=top> + <td>Address of Left Sibling</td> + <td> + <P>This is the relative file address of the left sibling of + the current node. If the current + node is the left-most node at this level then this field + is the <A href="#UndefinedAddress">undefined address</A>. + </P> + </td> + </tr> + + <tr valign=top> + <td>Address of Right Sibling</td> + <td> + <P>This is the relative file address of the right sibling of + the current node. If the current + node is the right-most node at this level then this + field is the <A href="#UndefinedAddress">undefined address</A>. + </P> + </td> + </tr> + + <tr valign=top> + <td>Keys and Child Pointers</td> + <td> + <P>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> + child pointers interleaved between the keys. The number + of keys and child pointers actually containing valid + values is determined by the node's <em>Entries Used</em> field. + If that field is <em>N</em> then the B-link tree contains + <em>N</em> child pointers and <em>N</em>+1 keys. + </P> + </td> + </tr> + + <tr valign=top> + <td>Key</td> + <td> + <P>The format and size of the key values is determined by + the type of data to which this tree points. The keys are + ordered and are boundaries for the contents of the child + pointer; that is, the key values represented by child + <em>N</em> fall between Key <em>N</em> and Key + <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the + tree points. + </P> + + <P> + The format of the key depends on the node type. + For nodes of node type 0 (group nodes), the key is formatted as + follows: + <center> + <table class=list> + <tr> + <td width=30%>A single field of <i>Size of Lengths</i> + bytes:</td> + <td>Indicates the byte offset into the local heap + for the first object name in the subtree which + that key describes. + </td> + </tr> + </table> + </center> + </P> + + <P> + For nodes of node type 1 (chunked raw data nodes), the key is + formatted as follows: + <center> + <table class=list> + <tr> + <td width=30%>Bytes 1-4:</td> + <td>Size of chunk in bytes.</td> + </tr> + <tr> + <td>Bytes 4-8:</td> + <td>Filter mask, a 32-bit bitfield indicating which + filters have been skipped for this chunk. Each filter + has an index number in the pipeline (starting at 0, with + the first filter to apply) and if that filter is skipped, + the bit corresponding to it's index is set.</td> + </tr> + <tr> + <td><em>N</em> 64-bit fields:</td> + <td>A 64-bit index indicating the offset of the + chunk within the dataset where <i>N</i> is the number + of dimensions of the dataset. For example, if + a chunk in a 3-dimensional dataset begins at the + position <code>[5,5,5]</code>, there will be three + such 64-bit indices, each with the value of + <code>5</code>.</td> + </tr> + </table> + </center> + </P> + </td> + </tr> + + <tr valign=top> + <td>Child Pointer</td> + <td> + <P>The tree node contains file addresses of subtrees or + data depending on the node level. Nodes at Level 0 point + to data addresses, either raw data chunk or group nodes. + Nodes at non-zero levels point to other nodes of the + same B-tree. + </P> + <P>For raw data chunk nodes, the child pointer is the address + of a single raw data chunk. For group nodes, the child pointer + points to a <A href="#SymbolTable">symbol table</A>, which contains + information for multiple symbol table entries. + </P> + </td> + </tr> + </table> + </div> + + <p> + Conceptually, each B-tree node looks like this: + <center> + <table> + <tr valign=top align=center> + <td>key[0]</td><td> </td> + <td>child[0]</td><td> </td> + <td>key[1]</td><td> </td> + <td>child[1]</td><td> </td> + <td>key[2]</td><td> </td> + <td>...</td><td> </td> + <td>...</td><td> </td> + <td>key[<i>N</i>-1]</td><td> </td> + <td>child[<i>N</i>-1]</td><td> </td> + <td>key[<i>N</i>]</td> + </tr> + </table> + </center> + <br> + + where child[<i>i</i>] is a pointer to a sub-tree (at a level + above Level 0) or to data (at Level 0). + Each key[<i>i</i>] describes an <i>item</i> stored by the B-tree + (a chunk or an object of a group node). The range of values + represented by child[<i>i</i>] is indicated by key[<i>i</i>] + and key[<i>i</i>+1]. + + + <p>The following question must next be answered: + "Is the value described by key[<i>i</i>] contained in + child[<i>i</i>-1] or in child[<i>i</i>]?" + The answer depends on the type of tree. + In trees for groups (node type 0) the object described by + key[<i>i</i>] is the greatest object contained in + child[<i>i</i>-1] while in chunk trees (node type 1) the + chunk described by key[<i>i</i>] is the least chunk in + child[<i>i</i>]. + + <p>That means that key[0] for group trees is sometimes unused; + it points to offset zero in the heap, which is always the + empty string and compares as "less-than" any valid object name. + + <p>And key[<i>N</i>] for chunk trees is sometimes unused; + it contains a chunk offset which compares as "greater-than" + any other chunk offset and has a chunk byte size of zero + to indicate that it is not actually allocated. + + + <h3><a name="SymbolTable">Disk Format: Level 1B - Group and Symbol Nodes</a></h3> + + <p>A group is an object internal to the file that allows + arbitrary nesting of objects within the file (including other groups). + A group maps a set of names in the group to a set of relative + file addresses where objects with those names are located in + the file. Certain metadata for an object to which the group points + can be cached in the group's symbol table in addition to the + object's header. + + <p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each + component in a group. The group entry for a + non-ultimate component points to the group containing + the next component. The group entry for the last + component points to the object being named. + + <p>A group is a collection of group nodes pointed + to by a B-link tree. Each group node contains entries + for one or more symbols. If an attempt is made to add a + symbol to an already full group node containing + 2<em>K</em> entries, then the node is split and one node + contains <em>K</em> symbols and the other contains + <em>K</em>+1 symbols. + + <br> + <div align=center> + <table class=format> + <caption> + Group Node (A Leaf of a B-tree) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + + <tr> + <td colspan=4>Signature</td> + + <tr> + <td>Version Number</td> + <td>Reserved (0)</td> + <td colspan=2>Number of Symbols</td> + + <tr> + <td colspan=4><br><br>Group Entries<br><br><br></td> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Signature</td> + <td> + <P>The ASCII character string "<code>SNOD</code>" is + used to indicate the + beginning of a group node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file. + </P> + </td> + </tr> + + <tr> + <td>Version Number</td> + <td> + <P>The version number for the group node. This + document describes version 1. (There is no version '0' + of the group node) + </P> + </td> + </tr> + + <tr> + <td>Number of Symbols</td> + <td> + <P>Although all group nodes have the same length, + most contain fewer than the maximum possible number of + symbol entries. This field indicates how many entries + contain valid data. The valid entries are packed at the + beginning of the group node while the remaining + entries contain undefined values. + </P> + </td> + </tr> + + <tr> + <td>Group Entries</td> + <td> + <P>Each symbol has an entry in the group node. + The format of the entry is described below. + There are 2<EM>K</EM> entries in each group node, where + <EM>K</EM> is the "Group Leaf Node K" value from the + <A href="#SuperBlock">super block</A>. + </P> + </td> + </tr> + </table> + </div> + + <h3><a name="SymbolTableEntry"> + Disk Format: Level 1C - Group Entry </a></h3> + + <p>Each group entry in a group node is designed + to allow for very fast browsing of stored objects. + Toward that design goal, the group entries + include space for caching certain constant metadata from the + object header. + + <br> + <div align=center> + <table class=format> + <caption> + Group Entry + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=4>Name Offset<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>Object Header Address<sup>O</sup></td> + </tr> + + <tr> + <td colspan=4>Cache Type</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4><br><br>Scratch-pad Space (16 bytes)<br><br><br></td> + </tr> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'O' the above table are + <br> + of the size specified in "Size of Offsets.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Name Offset</td> + <td> + <P>This is the byte offset into the group local + heap for the name of the object. The name is null + terminated. + </P> + </td> + </tr> + + <tr> + <td>Object Header Address</td> + <td> + <P>Every object has an object header which serves as a + permanent location for the object's metadata. In addition + to appearing in the object header, some metadata can be + cached in the scratch-pad space. + </P> + </td> + </tr> + + <tr> + <td>Cache Type</td> + <td> + <P>The cache type is determined from the object header. + It also determines the format for the scratch-pad space: + <br> + <table class=list> + <tr align=left> + <th>Type:</th> + <th>Description:</th> + </tr> + <tr> + <td width="10%" align=center>0</td> + <td>No data is cached by the group entry. This + is guaranteed to be the case when an object header + has a link count greater than one. + </td> + </tr> + <tr> + <td align=center>1</td> + <td>Object header metadata is cached in the group + entry. This implies that the group + entry refers to another group. + </td> + </tr> + <tr> + <td align=center>2</td> + <td>The entry is a symbolic link. The first four bytes + of the scratch-pad space are the offset into the local + heap for the link value. The object header address + will be undefined. + </td> + </tr> + <tr> + <td align=center><em>N</em></td> + <td>Other cache values can be defined later and + libraries that do not understand the new values will + still work properly. + </td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Reserved</td> + <td> + <P>These four bytes are present so that the scratch-pad + space is aligned on an eight-byte boundary. They are + always set to zero. + </P> + </td> + </tr> + + <tr> + <td>Scratch-pad Space</td> + <td> + <P>This space is used for different purposes, depending + on the value of the Cache Type field. Any metadata + about a dataset object represented in the scratch-pad + space is duplicated in the object header for that + dataset. This metadata can include the datatype + and the size of the dataspace for a dataset whose datatype + is atomic and whose dataspace is fixed and less than + four dimensions. + </P> + <P> + Furthermore, no data is cached in the group + entry scratch-pad space if the object header for + the group entry has a link count greater than + one. + </P> + </td> + </tr> + </table> + </div> + + <h4>Format of the Scratch-pad Space</h4> + + <p>The group entry scratch-pad space is formatted + according to the value in the Cache Type field. + + <p>If the Cache Type field contains the value zero + <code>(0)</code> then no information is + stored in the scratch-pad space. + + <p>If the Cache Type field contains the value one + <code>(1)</code>, then the scratch-pad space + contains cached metadata for another object header + in the following format: + + <br> + <div align=center> + <table class=format> + <caption> + Object Header Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + + <tr> + <td colspan=4>Address of B-tree<sup>O</sup></td> + + <tr> + <td colspan=4>Address of Name Heap<sup>O</sup></td> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'O' the above table are + <br> + of the size specified in "Size of Offsets.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Address of B-tree</td> + <td> + <P>This is the file address for the root of the + group's B-tree. + </P> + </td> + </tr> + + <tr> + <td>Address of Name Heap</td> + <td> + <P>This is the file address for the group's local + heap, in which are stored the group's symbol names. + </P> + </td> + </tr> + </table> + </div> + + + <P>If the Cache Type field contains the value two + <code>(2)</code>, then the scratch-pad space + contains cached metadata for another symbolic link + in the following format: + + <br> + <div align=center> + <table class=format> + <caption> + Symbolic Link Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=4>Offset to Link Value</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Offset to Link Value</td> + <td> + <P>The value of a symbolic link (that is, the name of the + thing to which it points) is stored in the local heap. + This field is the 4-byte offset into the local heap for + the start of the link value, which is null terminated. + </P> + </td> + </tr> + </table> + </div> + + <h3><a name="LocalHeap">Disk Format: Level 1D - Local Heaps</a></h3> + + <P>A heap is a collection of small heap objects. Objects can be + inserted and removed from the heap at any time. + The address of a heap does not change once the heap is created. + References to objects are stored in the group table; + the names of those objects are stored in the local heap. + </P> + + <br> + <div align=center> + <table class=format> + <caption> + Local Heap + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=4>Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Data Segment Size<sup>L</sup></td> + </tr> + + <tr> + <td colspan=4>Offset to Head of Free-list<sup>L</sup></td> + </tr> + + <tr> + <td colspan=4>Address of Data Segment<sup>O</sup></td> + </tr> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'L' the above table are + <br> + of the size specified in "Size of Lengths.") + </td></tr> + <tr><td> + (Items marked with an 'O' the above table are + <br> + of the size specified in "Size of Offsets.") + </td></tr> + </table> + </div> + + <p> + <center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Signature</td> + <td> + <P>The ASCII character string "<code>HEAP</code>" + is used to indicate the + beginning of a heap. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </P> + </td> + </tr> + + <tr> + <td>Version</td> + <td> + <P>Each local heap has its own version number so that new + heaps can be added to old files. This document + describes version zero (0) of the local heap. + </P> + </td> + </tr> + + <tr> + <td>Data Segment Size</td> + <td> + <P>The total amount of disk memory allocated for the heap + data. This may be larger than the amount of space + required by the objects stored in the heap. The extra + unused space in the heap holds a linked list of free blocks. + </P> + </td> + </tr> + + <tr> + <td>Offset to Head of Free-list</td> + <td> + <P>This is the offset within the heap data segment of the + first free block (or the + <A href="#UndefinedAddress">undefined address</A> if there is no + free block). The free block contains "Size of Lengths" bytes that + are the offset of the next free block (or the + value '1' if this is the + last free block) followed by "Size of Lengths" bytes that store + the size of this free block. The size of the free block includes + the space used to store the offset of the next free block and + the of the current block, making the minimum size of a free block + 2 * "Size of Lengths". + </P> + </td> + </tr> + + <tr> + <td>Address of Data Segment</td> + <td> + <P>The data segment originally starts immediately after + the heap header, but if the data segment must grow as a + result of adding more objects, then the data segment may + be relocated, in its entirety, to another part of the + file. + </P> + </td> + </tr> + </table> + </center> + + <p>Objects within the heap should be aligned on an 8-byte boundary. + + <h3><a name="GlobalHeap">Disk Format: Level 1E - Global Heap</a></h3> + + <P>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The + global heap was designed to satisfy these goals: + + <ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap + objects will typically be shared among several datasets, it is + probable that the object will be accessed repeatedly. + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of + object references will have a global heap object for each + reference. Reading the entire set of object references + should result in a few large I/O requests instead of one small + I/O request for each reference. + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed + for other uses. + </ol> + </P> + + <P>The implementation of the heap makes use of the memory + management already available at the file level and combines that + with a new top-level object called a <em>collection</em> to + achieve Goal B. The global heap is the set of all collections. + Each global heap object belongs to exactly one collection and + each collection contains one or more global heap objects. For + the purposes of disk I/O and caching, a collection is treated as + an atomic object. + </P> + + <P>The HDF5 library creates global heap collections as needed, so there may + be multiple collections throughout the file. The set of all of them is + abstractly called the "global heap", although they don't actually link + to each other, and there is no global place in the file where you can + discover all of the collections. The collections are found simply by + finding a reference to one through another object in the file (eg. + variable-length datatype elements, etc). + </P> + + <br> + <div align=center> + <table class=format> + <caption> + A Global Heap Collection + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=4>Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Collection Size<sup>L</sup></td> + </tr> + + <tr> + <td colspan=4><br>Global Heap Object 1<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Global Heap Object 2<br><br></td> + </tr> + + <tr> + <td colspan=4><br>...<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Global Heap Object <em>N</em><br><br></td> + </tr> + + <tr> + <td colspan=4><br>Global Heap Object 0 (free space)<br><br></td> + </tr> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'L' the above table are + <br> + of the size specified in "Size of Lengths.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Signature</td> + <td> + <P>The ASCII character string "<code>GCOL</code>" + is used to indicate the + beginning of a collection. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </P> + </td> + </tr> + + <tr> + <td>Version</td> + <td> + <P>Each collection has its own version number so that new + collections can be added to old files. This document + describes version one (1) of the collections (there is no + version zero (0)). + </P> + </td> + </tr> + + <tr> + <td>Collection Size</td> + <td> + <P>This is the size in bytes of the entire collection + including this field. The default (and minimum) + collection size is 4096 bytes which is a typical file + system block size. This allows for 127 16-byte heap + objects plus their overhead (the collection header of 16 bytes + and the 16 bytes of information about each heap object). + </P> + </td> + </tr> + + <tr> + <td>Global Heap Object 1 through <em>N</em></td> + <td> + <P>The objects are stored in any order with no + intervening unused space. + </P> + </td> + </tr> + + <tr> + <td>Global Heap Object 0</td> + <td> + <P>Global Heap Object 0 (zero), when present, represents the free + space in the collection. Free space always appears at the end of + the collection. If the free space is too small to store the header + for Object 0 (described below) then the header is implied and the + collection contains no free space. + </P> + </td> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Global Heap Object + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan=2>Heap Object ID</td> + <td colspan=2>Reference Count</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4>Object Size<sup>L</sup></td> + </tr> + + <tr> + <td colspan=4><br>Object Data<br><br></td> + </tr> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'L' the above table are + <br> + of the size specified in "Size of Lengths.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Heap Object ID</td> + <td> + <P>Each object has a unique identification number within a + collection. The identification numbers are chosen so that + new objects have the smallest value possible with the + exception that the identifier <code>0</code> always refers to the + object which represents all free space within the + collection. + </P> + </td> + </tr> + + <tr> + <td>Reference Count</td> + <td> + <P>All heap objects have a reference count field. An + object which is referenced from some other part of the + file will have a positive reference count. The reference + count for Object 0 is always zero. + </P> + </td> + </tr> + + <tr> + <td>Reserved</td> + <td> + <P>Zero padding to align next field on an 8-byte boundary. + </P> + </td> + </tr> + + <tr> + <td>Object Size</td> + <td> + <P>This is the size of the object data stored for the object. + The actual storage space allocated for the object data is rounded + up to a multiple of eight. + </P> + </td> + </tr> + + <tr> + <td>Object Data</td> + <td> + <P>The object data is treated as a one-dimensional array + of bytes to be interpreted by the caller. + </P> + </td> + </tr> + </table> + </div> + + <h3><a name="FreeSpaceIndex">Disk Format: Level 1F - Free-space Index</a></h3> + + <p>The free-space index is a collection of blocks of data, + dispersed throughout the file, which are currently not used by + any file objects. + + <p>The super block contains a pointer to root of the free-space description; + that pointer is currently required to be the + <A href="#UndefinedAddress">undefined address</A>. + + <p>The format of the free-space index is not defined at this time. + +<!-- + <p>The Free-space Index is a collection of blocks of data, + dispersed throughout the file, which are currently not used by + any file objects. The blocks of data are indexed by a B-tree of + their length within the file. + + + <p>Each B-tree page is composed of the following entries and + B-tree management information, organized as follows: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Free-space Heap Page</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Signature</td> + <tr align=center> + <td colspan=4>B-tree Left-link Offset</td> + <tr align=center> + <td colspan=4><br>Length of Free-block #1<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-block #1<br> <br></td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4><br>Length of Free-block #n<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-block #n<br> <br></td> + <tr align=center> + <td colspan=4>"High" Offset</td> + <tr align=center> + <td colspan=4>Right-link Offset</td> + </table> + </center> + + <p> + <dl> + <dt> The elements of the free-space heap page are described below: + <dd> + <dl> + <dt>Signature: (4 bytes) + <dd>The ASCII character string <code>FREE</code> + is used to indicate the + beginning of a free-space heap B-tree page. This gives + file consistency checking utilities a better chance of + reconstructing a damaged file. + + <dt>B-tree Left-link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of all offsets + in the B-link-tree which are smaller than the value of the + offset in entry #1. This value is also used to indicate a + leaf node in the B-link-tree by being set to all ones. + + <dt>Length of Free-block #n: (<length> bytes) + <dd>This value indicates the length of an unused block in + the file. + + <dt>Offset of Free-block #n: (<offset> bytes) + <dd>This value indicates the offset in the file of an + unused block in the file. + + <dt>"High" Offset: (4-bytes) + <dd>This offset is used as the upper bound on offsets + contained within a page when the page has been split. + + <dt>Right-link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of the next + child to the right of the parent of this group + page. When there is no node to the right, this value is + all zeros. + </dl> + </dl> + + <p>The algorithms for searching and inserting objects in the + B-tree pages are described fully in the Lehman and Yao paper, + which should be read to provide a full description of the + B-tree's usage. +--> + + <BR> + <HR> + + <h2><a name="DataObject">Disk Format: Level 2 - Data Objects </a></h2> + + <P>Data objects contain the real information in the file. These + objects compose the scientific data and other information which + are generally thought of as "data" by the end-user. All the + other information in the file is provided as a framework for + these data objects. + </P> + + <P>A data object is composed of header information and data + information. The header information contains the information + needed to interpret the data information for the data object as + well as additional "metadata" or pointers to additional + "metadata" used to describe or annotate each data object. + </P> + + <h3><a name="ObjectHeader"> + Disk Format: Level 2A - Data Object Headers</a></h3> + + <P>The header information of an object is designed to encompass + all the information about an object, except for the data itself. + This information includes + the dataspace, datatype, information about how the data + is stored on disk (in external files, compressed, broken up in + blocks, etc.), as well as other information used by the library + to speed up access to the data objects or maintain a file's + integrity. Information stored by user applications as attributes + is also stored in the object's header. The header of each object is + not necessarily located immediately prior to the object's data in the + file and in fact may be located in any position in the file. The order + of the messages in an object header is not significant. + </P> + + <P>Header messages are aligned on 8-byte boundaries. + </P> + + <br> + <div align=center> + <table class=format> + <caption> + Object Headers + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan=2>Number of Header Messages</td> + </tr> + + <tr> + <td colspan=4>Object Reference Count</td> + </tr> + + <tr> + <td colspan=4>Object Header Size</td> + </tr> + + <tr> + <td colspan=2>Header Message Type #1</td> + <td colspan=2>Size of Header Message Data #1</td> + </tr> + + <tr> + <td>Header Message #1 Flags</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4><br>Header Message Data #1<br><br></td> + </tr> + + <tr> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + + <tr> + <td colspan=2>Header Message Type #n</td> + <td colspan=2>Size of Header Message Data #n</td> + </tr> + + <tr> + <td>Header Message #n Flags</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4><br>Header Message Data #n<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>This value is used to determine the format of the + information in the object header. When the format of the + information in the object header is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + document describes version one (1) (there was no version + zero (0)). + </P> + </td> + </tr> + + <tr> + <td>Number of Header Messages</td> + <td> + <P>This value determines the number of messages listed in + object headers for this object. This value includes the messages + in continuation messages for this object. + </P> + </td> + </tr> + + <tr> + <td>Object Reference Count</td> + <td> + <P>This value specifies the number of "hard links" to this object + within the current file. References to the object from external + files, "soft links" in this file and object references in this + file are not tracked. + </P> + </td> + </tr> + + <tr> + <td>Object Header Size</td> + <td> + <P>This value specifies the number of bytes of header message data + following this length field that contain object header messages + for this object header. This value does not include the size of + object header continuation blocks for this object elsewhere in the + file. + </P> + </td> + </tr> + + <tr> + <td>Header Message Type</td> + <td> + <P>This value specifies the type of information included in the + following header message data. The header message types for the + pre-defined header messages are included in sections below. + </P> + </td> + </tr> + + <tr> + <td>Size of Header Message Data</td> + <td> + <P>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size includes + padding bytes to make the message a multiple of eight + bytes. + </P> + </td> + </tr> + + <tr> + <td>Header Message Flags</td> + <td> + <P>This is a bit field with the following definition: + <table class=list> + <tr> + <th width="30%">Bit</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>If set, the message data is constant. This is used + for messages like the datatype message of a dataset. + </td> + </tr> + <tr> + <td align=center><code>1</code></td> + <td>If set, the message is stored in the global heap. + The Header Message Data field contains a Shared Object + message and the Size of Header Message Data field + contains the size of that Shared Object message. + </td> + </tr> + <tr> + <td align=center><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Header Message Data</td> + <td> + <P>The format and length of this field is determined by the + header message type and size respectively. Some header + message types do not require any data and this information + can be eliminated by setting the length of the message to + zero. The data is padded with enough zeros to make the + size a multiple of eight. + </P> + </td> + </tr> + </table> + </div> + + <P>The header message types and the message data associated with + them compose the critical "metadata" about each object. Some + header messages are required for each object while others are + optional. Some optional header messages may also be repeated + several times in the header itself, the requirements and number + of times allowed in the header will be noted in each header + message description below. + </P> + + <P>The following is a list of currently defined header messages: + </P> + + <hr> + <h4><a name="NILMessage">Name: NIL</a></h4> + + <P class=item><B>Header Message Type: </B>0x0000 + </P> + <P class=item><B>Length:</B> varies + </P> + <P class=item><B>Status:</B> Optional, may be repeated. + </P> + <P class=item><B>Purpose and Description:</B> The NIL message is used to indicate a + message which is to be ignored when reading the header messages for a + data object. [Possibly one which has been deleted for some reason.] + </P> + <P class=item><B>Format of Data:</B> Unspecified. + </P> + + <hr> + <h4><a name="SimpleDataSpace">Name: Simple Dataspace</a></h4> + + <P class=item><B>Header Message Type: </B>0x0001 + </P> + <P class=item><B>Length:</B> Varies according to the number of dimensions, + as described in the following table. + </P> + <P class=item><B>Status:</B> Required for dataset objects, may not be + repeated. + </P> + <P class=item><B>Description:</B> The simple dataspace message describes the + number of dimensions (i.e. "rank") and size of each dimension that the + data object has. This message is only used for datasets which have a + simple, rectilinear grid layout; datasets requiring a more complex + layout (irregularly structured or unstructured grids, etc.) must use + the <em>Complex Dataspace</em> message for expressing the space the + dataset inhabits. <i>(Note: The <em>Complex Dataspace</em> + functionality is not yet implemented and it is not described in this + document.)</i> + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Simple Dataspace Message + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4>Dimension #1 Size<sup>L</sup></td> + <tr> + <td colspan=4>.<br>.<br>.<br></td> + <tr> + <td colspan=4>Dimension #n Size<sup>L</sup></td> + <tr> + <td colspan=4>Dimension #1 Maximum Size<sup>L</sup></td> + <tr> + <td colspan=4>.<br>.<br>.<br></td> + <tr> + <td colspan=4>Dimension #n Maximum Size<sup>L</sup></td> + <tr> + <td colspan=4>Permutation Index #1<sup>L</sup></td> + <tr> + <td colspan=4>.<br>.<br>.<br></td> + <tr> + <td colspan=4>Permutation Index #n<sup>L</sup></td> + </table> + + <table class=note> + <tr><td> + (Items marked with an 'L' the above table are + <br> + of the size specified in "Size of Lengths.") + </td></tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>This value is used to determine the format of the + Simple Dataspace Message. When the format of the + information in the message is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + document describes version one (1) (there was no version + zero (0)). + </P> + </td> + </tr> + + <tr> + <td>Dimensionality</td> + <td> + <P>This value is the number of dimensions that the data + object has. + </P> + </td> + </tr> + + <tr> + <td>Flags</td> + <td> + <P>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. Bit 1 is used to indicate that + permutation indices are present. + </P> + </td> + </tr> + + <tr> + <td>Dimension #n Size</td> + <td> + <P>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </P> + </td> + </tr> + + <tr> + <td>Dimension #n Maximum Size</td> + <td> + <P>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + "<A href="#UnlimitedDim">unlimited</A>" size which indicates + that the data may expand along this dimension indefinitely. + If these values are not stored, the maximum size of each + dimension is assumed to be the dimension's current size. + </P> + </td> + </tr> + + <tr> + <td>Permutation Index #n</td> + <td> + <P>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. If these values are + not stored, the first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </P> + </td> + </tr> + </table> + </div> + + </P> + +<!-- + <hr> + <h4><a name="DataSpaceMessage">Name: Complex Dataspace (Fiber Bundle?)</a></h4> + <b>Header Message Type: </b>0x0002<br> + <b>Length:</b> varies<br> + + <b>Status:</b> One of the <em>Simple Dataspace</em> or + <em>Complex Dataspace</em> messages is required (but not both) and may + not be repeated.<br> <b>Purpose and Description:</b> The + <em>Dataspace</em> message describes space that the dataset is + mapped onto in a more comprehensive way than the <em>Simple + Dimensionality</em> message is capable of handling. The + dataspace of a dataset encompasses the type of coordinate system + used to locate the dataset's elements as well as the structure and + regularity of the coordinate system. The dataspace also + describes the number of dimensions which the dataset inhabits as + well as a possible higher dimensional space in which the dataset + is located within. + + <br> + <b>Format of Data:</b> + + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Message Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Mesh Type</td> + <tr align=center> + <td colspan=4>Logical Dimensionality</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br> + The mesh type value is broken up as follows: <br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Mesh-type Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=1>Mesh Embedding</td> + <td colspan=1>Coordinate System</td> + <td colspan=1>Structure</td> + <td colspan=1>Regularity</td> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset dataspace + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset's dataspace is located within + another dataspace, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric datatype. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed: + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + dataspace. + <br> <br> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Embedded Dimensionality Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Embedded Dimensionality</td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #n</td> + <tr align=center> + <td colspan=4>Embedded Origin Location #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Origin Location #n</td> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located + within. i.e. a planar dataset located within a 3-D space, + or a 3-D dataset + which is a subset of another 3-D space, etc. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded dataspace + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset's + origin within the embedded dataspace. + </dl> + </dl> + [Comment: need some way to handle different orientations of the + dataset dataspace + within the embedded dataspace]<br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Structured/Regular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Logical Dimension Size #1</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Logical Dimension Size #n</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #n</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> + </dl> + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Structured/Irregular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4># of Grid Points in Dimension #n</td> + <tr align=center> + <td colspan=4>Datatype of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #n</td> + </table> + </center> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Dataspace Unstructured Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points</td> + <tr align=center> + <td colspan=4>Datatype of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Grid Point Locations<br>.<br>.<br></td> + </table> + </center> +--> + + <hr> + <h4><a name="ReservedMessage_0002">Name: Reserved - Not Assigned Yet</a></h4> + <b>Header Message Type:</b> 0x0002<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + <b>Format of Data:</b> N/A<BR> + + <p><b>Purpose and Description:</b> This message type was skipped during + the initial specification of the file format and may be used in a + future expansion to the format. + + + <hr> + <h4><a name="DataTypeMessage">Name: Datatype</a></h4> + + <P class=item><B>Header Message Type:</B> 0x0003 + </P> + <P class=item><B>Length:</B> variable + </P> + <P class=item><B>Status:</B> Required for dataset or named datatype objects, + may not be repeated. + </P> + + <P class=item><B>Description:</B> The datatype message defines the datatype + for each element of a dataset. A datatype can describe an atomic type + like a fixed- or floating-point type or a compound type like a C + struct. + Datatypes messages are stored + as a list of datatype classes and + their associated properties. + </P> + + <P class=item2>Datatype messages that are part of a dataset object, + do not describe how elements are related to one another, the dataspace + message is used for that purpose. Datatype messages that are part of + a named datatype message describe an "abstract" datatype that can be + used by other objects in the file. + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Datatype Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Class and Version</td> + <td>Class Bit Field, Bits 0-7</td> + <td>Class Bit Field, Bits 8-15</td> + <td>Class Bit Field, Bits 16-23</td> + </tr> + + <tr> + <td colspan=4>Size</td> + </tr> + + <tr> + <td colspan=4><br><br>Properties<br><br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Class and Version</td> + <td> + <P>The version of the datatype message and the datatype's class + information are packed together in this field. The version + number is packed in the top 4 bits of the field and the class + is contained in the bottom 4 bits. + </P> + <P>The version number information is used for changes in the + format of the datatype message and is described here: + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align=center><code>1</code></td> + <td>Used by early versions of the library to encode + compound datatypes with explicit array fields. + See the compound datatype description below for + further details. + </td> + </tr> + <tr> + <td align=center><code>2</code></td> + <td>The current version used by the library. + </td> + </tr> + </table> + </P> + <P>The class of the datatype determines the format for the class + bit field and properties portion of the datatype message, which + are described below. The + following classes are currently defined: + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Fixed-Point</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Floating-Point</td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Time</td> + </tr> + + <tr> + <td align=center><code>3</code></td> + <td>String</td> + </tr> + + <tr> + <td align=center><code>4</code></td> + <td>Bitfield</td> + </tr> + + <tr> + <td align=center><code>5</code></td> + <td>Opaque</td> + </tr> + + <tr> + <td align=center><code>6</code></td> + <td>Compound</td> + </tr> + + <tr> + <td align=center><code>7</code></td> + <td>Reference</td> + </tr> + + <tr> + <td align=center><code>8</code></td> + <td>Enumerated</td> + </tr> + + <tr> + <td align=center><code>9</code></td> + <td>Variable-Length</td> + </tr> + + <tr> + <td align=center><code>10</code></td> + <td>Array</td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Class Bit Fields</td> + <td> + <P>The information in these bit fields is specific to each datatype + class and is described below. All bits not defined for a + datatype class are set to zero. + </P> + </td> + </tr> + + <tr> + <td>Size</td> + <td> + <P>The size of the datatype in bytes. + </P> + </td> + </tr> + + <tr> + <td>Properties</td> + <td> + <P>This variable-sized field encodes information specific to each + datatype class and is described below. If there is no + property information specified for a datatype class, the size + of this field is zero. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Fixed-Point Numbers (Class 0): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1, 2</td> + <td><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</td> + </tr> + + <tr> + <td>3</td> + <td><b>Signed.</b> If this bit is set then the fixed-point + number is in 2's complement form.</td> + </tr> + + <tr> + <td>4-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Bit Offset</td> + <td> + <P>The bit offset of the first significant bit of the fixed-point + value within the datatype. The bit offset specifies the number + of bits "to the right of" the value. + </P> + </td> + </tr> + + <tr> + <td>Bit Precision</td> + <td> + <P>The number of bits of precision of the fixed-point value + within the datatype. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Floating-Point Numbers (Class 1): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1, 2, 3</td> + <td><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 + is the high bits pad type, and bit 3 is the internal bits + pad type. If a datum has unused bits at either end or between + the sign bit, exponent, or mantissa, then the value of bit + 1, 2, or 3 is copied to those locations.</td> + </tr> + + <tr> + <td>4-5</td> + <td><b>Normalization.</b> The value can be 0 if there is no + normalization, 1 if the most significant bit of the + mantissa is always set (except for 0.0), and 2 if the most + signficant bit of the mantissa is not stored but is + implied to be set. The value 3 is reserved and will not + appear in this field.</td> + </tr> + + <tr> + <td>6-7</td> + <td>Reserved (zero).</td> + </tr> + + <tr> + <td>8-15</td> + <td><b>Sign Location.</b> This is the bit position of the sign + bit. Bits are numbered with the least significant bit zero.</td> + </tr> + + <tr> + <td>16-23</td> + <td>Reserved (zero).</td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + + <tr> + <td>Exponent Location</td> + <td>Exponent Size</td> + <td>Mantissa Location</td> + <td>Mantissa Size</td> + </tr> + + <tr> + <td colspan=4>Exponent Bias</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Bit Offset</td> + <td> + <P>The bit offset of the first significant bit of the floating-point + value within the datatype. The bit offset specifies the number + of bits "to the right of" the value. + </P> + </td> + </tr> + + <tr> + <td>Bit Precision</td> + <td> + <P>The number of bits of precision of the floating-point value + within the datatype. + </P> + </td> + </tr> + + <tr> + <td>Exponent Location</td> + <td> + <P>The bit position of the exponent field. Bits are numbered with + the least significant bit number zero. + </P> + </td> + </tr> + + <tr> + <td>Exponent Size</td> + <td> + <P>The size of the exponent field in bits. + </P> + </td> + </tr> + + <tr> + <td>Mantissa Location</td> + <td> + <P>The bit position of the mantissa field. Bits are numbered with + the least significant bit number zero. + </P> + </td> + </tr> + + <tr> + <td>Mantissa Size</td> + <td> + <P>The size of the mantissa field in bits. + </P> + </td> + </tr> + + <tr> + <td>Exponent Bias</td> + <td> + <P>The bias of the exponent field. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Time (Class 2): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Bit Precision</td> + <td> + <P>The number of bits of precision of the time value. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Strings (Class 3): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-3</td> + <td><b>Padding type.</b> This four-bit value determines the + type of padding to use for the string. The values are: + + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Null Terminate: A zero byte marks the end of the + string and is guaranteed to be present after + converting a long string to a short string. When + converting a short string to a long string the value is + padded with additional null characters as necessary. + </td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Null Pad: Null characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. + </td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Space Pad: Space characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align=center><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table> + </tr> + + <tr> + <td>4-7</td> + <td><b>Character Set.</b> The character set to use for + encoding the string. The only character set supported is + the 8-bit ASCII (zero) so no translations have been defined + yet.</td> + </tr> + + <tr> + <td>8-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <P>There are no properties defined for the string class. + </P> + </P> + + <P>Class specific information for Bitfields (Class 4): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1, 2</td> + <td><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</td> + </tr> + + <tr> + <td>3-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Bit Offset</td> + <td> + <P>The bit offset of the first significant bit of the bitfield + within the datatype. The bit offset specifies the number + of bits "to the right of" the value. + </P> + </td> + </tr> + + <tr> + <td>Bit Precision</td> + <td> + <P>The number of bits of precision of the bitfield + within the datatype. + </P> + </td> + </tr> + </table> + </div> + </P> + + <P>Class specific information for Opaque (Class 5): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-7</td> + <td>Length of ASCII tag in bytes.</td> + </tr> + + <tr> + <td>8-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=4><br>ASCII Tag<br> + <br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>ASCII Tag</td> + <td> + <P>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </P> + </td> + </tr> + </table> + </div> + </P> + + <P>Class specific information for Compound (Class 6): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-15</td> + <td><b>Number of Members.</b> This field contains the number + of members defined for the compound datatype. The member + definitions are listed in the Properties field of the data + type message. + </tr> + + <tr> + <td>15-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + </P> + + <P>The Properties field of a compound datatype is a list of the + member definitions of the compound datatype. The member + definitions appear one after another with no intervening bytes. + The member types are described with a recursive datatype + message. + + <P>Note that the property descriptions are different for different + versions of the datatype version. Additionally note that the version + 0 properties are deprecated and have been replaced with the version + 1 properties in versions of the HDF5 library from the 1.4 release + onward. + + <br> + <div align=center> + <table class=format> + <caption> + Properties Description for Datatype Version 1 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr> + <td colspan=4>Byte Offset of Member</td> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Dimension Permutation</td> + </tr> + + <tr> + <td colspan=4>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Dimension #1 Size (required)</td> + </tr> + + <tr> + <td colspan=4>Dimension #2 Size (required)</td> + </tr> + + <tr> + <td colspan=4>Dimension #3 Size (required)</td> + </tr> + + <tr> + <td colspan=4>Dimension #4 Size (required)</td> + </tr> + + <tr> + <td colspan=4><br>Member Type Message<br><br></td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Name</td> + <td> + <P>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </P> + </td> + </tr> + + <tr> + <td>Byte Offset of Member</td> + <td> + <P>This is the byte offset of the member within the datatype. + </P> + </td> + </tr> + + <tr> + <td>Dimensionality</td> + <td> + <P>If set to zero, this field indicates a scalar member. If set + to a value greater than zero, this field indicates that the + member is an array of values. For array members, the size of + the array is indicated by the 'Size of Dimension n' field in + this message. + </P> + </td> + </tr> + + <tr> + <td>Dimension Permutation</td> + <td> + <P>This field was intended to allow an array field to have + it's dimensions permuted, but this was never implemented. + This field should always be set to zero. + </P> + </td> + </tr> + + <tr> + <td>Dimension #n Size</td> + <td> + <P>This field is the size of a dimension of the array field as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </P> + </td> + </tr> + + <tr> + <td>Member Type Message</td> + <td> + <P>This field is a datatype message describing the datatype of + the member. + </P> + </td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Properties Description for Datatype Version 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr> + <td colspan=4>Byte Offset of Member</td> + </tr> + + <tr> + <td colspan=4><br>Member Type Message<br><br></td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Name</td> + <td> + <P>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </P> + </td> + </tr> + + <tr> + <td>Byte Offset of Member</td> + <td> + <P>This is the byte offset of the member within the datatype. + </P> + </td> + </tr> + + <tr> + <td>Member Type Message</td> + <td> + <P>This field is a datatype message describing the datatype of + the member. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Reference (Class 7): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-3</td> + <td><b>Type.</b> This four-bit value contains the type of reference + described. The values defined are: + + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Object Reference: A reference to another object in this + HDF5 file. + </td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Dataset Region Reference: A reference to a region within + a dataset in this HDF5 file. + </td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Internal Reference: A reference to a region within the + current dataset. (Not currently implemented) + </td> + </tr> + + <tr> + <td align=center><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table> + + </td> + </tr> + + <tr> + <td>15-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <P>There are no properties defined for the reference class. + </P> + </P> + + <P>Class specific information for Enumeration (Class 8): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-15</td> + <td><b>Number of Members.</b> The number of name/value + pairs defined for the enumeration type.</td> + </tr> + + <tr> + <td>16-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=4><br>Base Type<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Names<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Values<br><br></td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Base Type</td> + <td> + <P>Each enumeration type is based on some parent type, usually an + integer. The information for that parent type is described + recursively by this field. + </P> + </td> + </tr> + + <tr> + <td>Names</td> + <td> + <P>The name for each name/value pair. Each name is stored as a null + terminated ASCII string in a multiple of eight bytes. The names + are in no particular order. + </P> + </td> + </tr> + + <tr> + <td>Values</td> + <td> + <P>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value + is determined by the parent type. + </P> + </td> + </tr> + + </table> + </div> + </P> + + + <P>Class specific information for Variable-Length (Class 9): + + <br> + <div align=center> + <table class=desc> + <caption> + Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0-3</td> + <td><b>Type.</b> This four-bit value contains the type of + variable-length datatype described. The values defined are: + + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Sequence: A variable-length sequence of any sequence of + data. Variable-length sequences do not have padding or + character set information. + </td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>String: A variable-length sequence of characters. + Variable-length strings have padding and character set + information. + </td> + </tr> + + <tr> + <td align=center><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table> + + </td> + </tr> + + <tr> + <td>4-7</td> + <td><b>Padding type.</b> (variable-length string only) + This four-bit value determines the type of padding + used for variable-length strings. The values are the same + as for the string padding type, as follows: + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Null terminate: A zero byte marks the end of a string + and is guaranteed to be present after converting a long + string to a short string. When converting a short string + to a long string, the value is padded with additional null + characters as necessary. + </td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Null pad: Null characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. + </td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Space pad: Space characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align=center><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table> + + This value is set to zero for variable-length sequences. + + </td> + </tr> + + <tr> + <td>8-11</td> + <td><b>Character Set.</b> (variable-length string only) + This four-bit value specifies the character set + to be used for encoding the string: + <table width=100% class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>ASCII: As of this writing (July 2003, Release 1.6.0), + 8-bit ASCII is the only character set supported. Therefore, + no translations have been defined. + </td> + </tr> + + <tr> + <td align=center><code>1-15</code></td> + <td>Reserved + </td> + </tr> + </table> + + This value is set to zero for variable-length sequences. + + </td> + </tr> + + <tr> + <td>12-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan=4><br>Base Type<br><br></td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Base Type</td> + <td> + <P>Each variable-length type is based on some parent type. The + information for that parent type is described recursively by + this field. + </P> + </td> + </tr> + + </table> + </div> + </P> + + <P>Class specific information for Array (Class 10): + + <P>There are no bit fields defined for the array class. + </P> + + <P>Note that the dimension information defined in the property for this + datatype class is independent of dataspace information for a dataset. + The dimension information here describes the dimensionality of the + information within a data element (or a component of an element, if the + array datatype is nested within another datatype) and the dataspace for a + dataset describes the location of the elements in a dataset. + </P> + + <br> + <div align=center> + <table class=format> + <caption> + Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan=3>Reserved (zero)</td> + </tr> + + <tr> + <td colspan=4>Dimension #1 Size</td> + </tr> + <tr> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr> + <td colspan=4>Dimension #n Size</td> + </tr> + + <tr> + <td colspan=4>Permutation Index #1</td> + </tr> + <tr> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr> + <td colspan=4>Permutation Index #n</td> + </tr> + + <tr> + <td colspan=4><br>Base Type<br><br></td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td> + <P>This value is the number of dimensions that the array has. + </P> + </td> + </tr> + + <tr> + <td>Dimension #n Size</td> + <td> + <P>This value is the size of the dimension of the array + as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </P> + </td> + </tr> + + <tr> + <td>Permutation Index #n</td> + <td> + <P>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. Currently, dimension + permutations are not supported and these indices should be set + to the index position minus one (i.e. the first dimension should + be set to 0, the second dimension should be set to 1, etc.) + </P> + </td> + </tr> + + <tr> + <td>Base Type</td> + <td> + <P>Each array type is based on some parent type. The + information for that parent type is described recursively by + this field. + </P> + </td> + </tr> + + </table> + </div> + + </P> + + <hr> + <h4><a name="OldFillValueMessage">Name: Data Storage - Fill Value (Old)</a></h4> + + <P class=item><B>Header Message Type:</B> 0x0004 + </P> + <P class=item><B>Length:</B> varies + </P> + <P class=item><B>Status:</B> Optional, may not be repeated. + </P> + + <P class=item><B>Description:</B> The fill value message stores a single + data value which is returned to the application when an uninitialized + data element is read from a dataset. The fill value is interpreted + with the same datatype as the dataset. If no fill value message is + present then a fill value of all zero bytes is assumed. + </P> + + <P class=item2>This fill value message is deprecated in favor of the "new" + fill value message (Message Type 0x0005) and is only written to the + file for forward compatibility with versions of the HDF5 library before + the 1.6.0 version. Additionally, it only appears for datasets with a + user defined fill value (as opposed to the library default fill value + or an explicitly set "undefined" fill value). + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Fill Value Message (Old) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4>Size</td> + </tr> + + <tr> + <td colspan=4><br>Fill Value<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Size</td> + <td> + <P>This is the size of the Fill Value field in bytes. + </P> + </td> + </tr> + + <tr> + <td>Fill Value</td> + <td> + <P>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. + </P> + </td> + </tr> + </table> + </div> + </P> + + <hr> + <h4><a name="FillValueMessage">Name: Data Storage - Fill Value </a></h4> + + <P class=item><B>Header Message Type:</B> 0x0005 + </P> + <P class=item><B>Length:</B> varies + </P> + <P class=item><B>Status:</B> Required for dataset objects, may not be repeated. + </P> + + <P class=item><B>Description:</B> The fill value message stores a single + data value which is returned to the application when an uninitialized + data element is read from a dataset. The fill value is interpreted + with the same datatype as the dataset. + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Fill Value Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Space Allocation Time</td> + <td>Fill Value Write Time</td> + <td>Fill Value Defined</td> + </tr> + + <tr> + <td colspan=4>Size</td> + </tr> + + <tr> + <td colspan=4><br>Fill Value<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>The version number information is used for changes in the + format of the fill value message and is described here: + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align=center><code>1</code></td> + <td>Used by version 1.6.x of the library to encode + fill values. In this version, the Size field is + always present. + </td> + </tr> + <tr> + <td align=center><code>2</code></td> + <td>The current version used by the library (version + 1.7.3 or later). In this version, the Size and + Fill Value fields are + only present if the Fill Value Defined field is set + to 1. + </td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Space Allocation Time</td> + <td> + <P>When the storage space for the dataset's raw data will be + allocated. The allowed values are: + <table class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Early allocation. Storage space for the entire dataset + should be allocated in the file when the dataset is + created. + </td> + </tr> + <tr> + <td align=center><code>2</code></td> + <td>Late allocation. Storage space for the entire dataset + should not be allocated until the dataset is written + to. + </td> + </tr> + <tr> + <td align=center><code>3</code></td> + <td>Incremental allocation. Storage space for the + dataset should not be allocated until the portion + of the dataset is written to. This is currently + used in conjunction with chunked data storage for + datasets. + </td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Fill Value Write Time</td> + <td> + <P>At the time that storage space for the dataset's raw data is + allocated, this value indicates whether the fill value should + be written to the raw data storage elements. The allowed values + are: + <table class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>On allocation. The fill value is always written to + the raw data storage when the storage space is allocated. + </td> + </tr> + <tr> + <td align=center><code>1</code></td> + <td>Never. The fill value should never be written to + the raw data storage. + </td> + </tr> + <tr> + <td align=center><code>2</code></td> + <td>Fill value written if set by user. The fill value + will be written to the raw data storage when the storage + space is allocated only if the user explicitly set + the fill value. If the fill value is the library + default or is undefined, it will not be written to + the raw data storage. + </td> + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Fill Value Defined</td> + <td> + <P>This value indicates if a fill value is defined for this + dataset. If this value is 0, the fill value is undefined. + If this value is 1, a fill value is defined for this dataset. + For version 2 or later of the fill value message, this value + controls the presence of the Size field. + </P> + </td> + </tr> + + <tr> + <td>Size</td> + <td> + <P>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is >1 and the Fill Value + Defined field is set to 0. + </P> + </td> + </tr> + + <tr> + <td>Fill Value</td> + <td> + <P>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is + not present if the Version field is >1 and the Fill Value + Defined field is set to 0. + </P> + </td> + </tr> + </table> + </div> + </P> + +<!-- + <hr> + <h4><a name="CompactDataStorageMessage">Name: Data Storage - Compact</a></h4> + + <b>Header Message Type:</b> 0x0006<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may not be repeated.<br> + + <p>This message indicates that the data for the data object is + stored within the current HDF file by including the actual + data as the header data for this message. The data is + stored internally in + the <em>normal format</em>, i.e. in one chunk, uncompressed, etc. + + <P>Note that one and only one of the <em>Data Storage</em> headers can be + stored for each data object. + + <P><b>Format of Data:</b> The message data is actually composed + of dataset data, so the format will be determined by the dataset + format. +--> + + <hr> + <h4><a name="ReservedMessage_0006">Name: Reserved - Not Assigned Yet</a></h4> + <P class=item><B>Header Message Type:</B> 0x0006</P> + <P class=item><B>Length:</B> N/A</P> + <P class=item><B>Status:</B> N/A</P> + <P class=item><B>Format of Data:</B> N/A</P> + + <P class=item><B>Purpose and Description:</B> This message type was skipped during + the initial specification of the file format and may be used in a + future expansion to the format.</P> + + <hr> + <h4><a name="ExternalFileListMessage">Name: Data Storage - + External Data Files</a></h4> + <P class=item><B>Header Message Type:</B> 0x0007 </P> + <P class=item><B>Length:</B> varies</P> + <P class=item><B>Status:</B> Optional, may not be repeated.</P> + + <P class=item><B>Purpose and Description:</B> The external object message + indicates that the data for an object is stored outside the HDF5 + file. The filename of the object is stored as a Universal + Resource Location (URL) of the actual filename containing the + data. An external file list record also contains the byte offset + of the start of the data within the file and the amount of space + reserved in the file for that data.</P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + External File List Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan=3>Reserved</td> + </tr> + + <tr> + <td colspan=2>Allocated Slots</td> + <td colspan=2>Used Slots</td> + </tr> + + <tr> + <td colspan=4><br>Heap Address<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Slot Definitions...<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>The version number information is used for changes in the format of External File + List Message and is described here: + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + <tr> + <td align=center><code>0</code></td> + <td>Never used. + </tr> + <tr> + <td align=center><code>1</code></td> + <td>The current version used by the library. + </tr> + </table> + </P> + </td> + </tr> + + <tr> + <td>Reserved</td> + <td> + <P>This field is reserved for future use.</P> + </td> + </tr> + + <tr> + <td>Allocated Slots</td> + <td> + <P>The total number of slots allocated in the message. Its value must be at least as + large as the value contained in the Used Slots field. (The current library simply + uses the number of Used Slots for this message)</P> + </td> + </tr> + + <tr> + <td>Used Slots</td> + <td> + <P>The number of initial slots which contains valid information.</P> + </td> + </tr> + + <tr> + <td>Heap Address</td> + <td> + <P>This is the address of a local heap which contains the names for the external + files (The local heap information can be found in Disk Format Level 1D in this + document). The name at offset zero in the heap is always the empty string.</P> + </td> + </tr> + + <tr> + <td>Slot Definitions</td> + <td> + <P>The slot definitions are stored in order according to the array addresses they + represent.</P> + </td> + </tr> + + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + External File List Slot + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4><br>Name Offset(<size> bytes)<br><br></td> + </tr> + + <tr> + <td colspan=4><br>File Offset(<size> bytes)<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Size<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Name Offset(<size> bytes)</td> + <td> + <P>The byte offset within the local name heap for the name + of the file. File names are stored as a URL which has a + protocol name, a host name, a port number, and a file + name: + <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. + If the protocol is omitted then "file:" is assumed. If + the port number is omitted then a default port for that + protocol is used. If both the protocol and the port + number are omitted then the colon can also be omitted. If + the double slash and host name are omitted then + "localhost" is assumed. The file name is the only + mandatory part, and if the leading slash is missing then + it is relative to the application's current working + directory (the use of relative names is not + recommended).</P> + </td> + </tr> + + <tr> + <td>File Offset(<size> bytes)</td> + <td> + <P>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single + dataset this will usually be zero.</P> + </td> + </tr> + + <tr> + <td>Size</td> + <td> + <P>This is the total number of bytes reserved in the + specified file for raw data storage. For a file that + contains exactly one complete dataset which is not + extendable, the size will usually be the exact size of the + dataset. However, by making the size larger one allows + HDF5 to extend the dataset. The size can be set to a value + larger than the entire file since HDF5 will read zeros + past the end of the file without failing.</P> + </td> + </tr> + </table> + </div> + + + <hr> + <h4><a name="LayoutMessage">Name: Data Storage - Layout</a></h4> + + <P class=item><B>Header Message Type:</B> 0x0008</P> + <P class=item><B>Length:</B> varies</P> + <P class=item><B>Status:</B> Required for datasets, may not be repeated.</P> + + <P class=item><B>Purpose and Description:</B> Data layout describes how the + elements of a multi-dimensional array are arranged in the linear + address space of the file. Three types of data layout are + supported: + + <ol> + <li>Contiguous: The array can be stored in one contiguous area of the file. + The layout requires that the size of the array be constant and + does not permit chunking, compression, checksums, encryption, + etc. The message stores the total size of the array and the + offset of an element from the beginning of the storage area is + computed as in C. + + <li>Chunked: The array domain can be regularly decomposed into chunks and + each chunk is allocated separately. This layout supports + arbitrary element traversals, compression, encryption, and + checksums, and the chunks can be distributed across external + raw data files (these features are described in other + messages). The message stores the size of a chunk instead of + the size of the entire array; the size of the entire array can + be calculated by traversing the B-tree that stores the chunk + addresses. + + <li>Compact: The array can be stored in one contiguous block, as part of + this object header message (this is called "compact" storage below). + </ol> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Data Layout Message (Versions 1 and 2) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Layout Class</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4><br>Address<br><br></td> + </tr> + + <tr> + <td colspan=4>Dimension 0 (4-bytes)</td> + </tr> + + <tr> + <td colspan=4>Dimension 1 (4-bytes)</td> + </tr> + + <tr> + <td colspan=4>...</td> + </tr> + + <tr> + <td colspan=4>Dataset Element Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan=4>Compact Data Size (4-bytes)</td> + </tr> + + <tr> + <td colspan=4><br>Compact Data...<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>The version number information is used for changes in the format of the data + layout message and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Used by version 1.4 and before of the library to encode layout information. + Data space is always allocated when the data set is created.</td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Used by version 1.6.x of the library to encode layout information. + Data space is allocated only when it is necessary.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Dimensionality</td> + <td><P>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the + message.</P></td> + </tr> + + <tr> + <td>Layout Class</td> + <td><P>The layout class specifies how the other fields of the + layout message are to be interpreted. A value of one + indicates contiguous storage, a value of two indicates chunked storage, + while a value of zero indicates compact storage. Other values will be defined + in the future.</P></td> + </tr> + + <tr> + <td>Address</td> + <td><P>For contiguous storage, this is the address of the first + byte of storage. For chunked storage this is the address + of the B-tree that is used to look up the addresses of the + chunks. This field is not present for compact storage. + If the version for this message is set to 2, the address + may have the "undefined address" value, to indicate that + storage has not yet been allocated for this array.</P></td> + </tr> + + <tr> + <td>Dimensions</td> + <td><P>For contiguous and compact storage the dimensions define + the entire size of the array while for chunked storage they define + the size of a single chunk. In all cases, they are in units of + array elements (not bytes). The first dimension stored in the list + of dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </P> + </td> + </tr> + + <tr> + <td>Dataset Element Size</td> + <td><P>The size of a dataset element, in bytes. This field is only + present for chunked storage. + </P> + </td> + </tr> + + <tr> + <td>Compact Data Size</td> + <td><P>This field is only present for compact data storage. + It contains the size of the raw data for the dataset array.</P></td> + + <tr> + <td>Compact Data</td> + <td><P>This field is only present for compact data storage. + It contains the raw data for the dataset array.</P></td> + </tr> + </table> + </div> + + <br> + <P>Version 3 of this message re-structured the format into specific + properties that are required for each layout class. + + <br> + <div align=center> + <table class=format> + <caption> + <B>Data Layout Message (Version 3)</B> + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Layout Class</td> + <td colspan=2 bgcolor=#DDDDDD> </td> + </tr> + + <tr> + <td colspan=4><br>Properties<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td> + <P>The version number information is used for changes in the format of layout message + and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>3</code></td> + <td>Used by the version 1.6.3 and later of the library to store properties + for each layout class.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Layout Class</td> + <td><P>The layout class specifies how the other fields of the layout message are to be + interpreted. A value of one indicates contiguous storage, a value of two + indicates chunked storage, while a value of zero indicates compact storage.</P></td> + </tr> + + <tr> + <td>Properties</td> + <td><P>This variable-sized field encodes information specific to each + layout class and is described below. If there is no property + information specified for a layout class, the size of this field + is zero bytes.</P></td> + </tr> + </table> + </div> + + <br> + <P>Class-specific information for compact layout (Class 0): (Note: The dimensionality information + is in the Dataspace message) + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=2>Size</td> + <td colspan=2 bgcolor=#DDDDDD> </td> + </tr> + + <tr> + <td colspan=4><br>Raw Data...<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Size</td> + <td><P>This field contains the size of the raw data for the dataset array.</P></td> + </tr> + + <tr> + <td>Raw Data</td> + <td><P>This field contains the raw data for the dataset array.</P></td> + </tr> + </table> + </div> + + <br> + <P>Class-specific information for contiguous layout (Class 1): (Note: The dimensionality information + is in the Dataspace message) + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4><br>Address<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Size<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Address</td> + <td><P>This is the address of the first byte of raw data storage. + The address may have the "undefined address" value, to indicate + that storage has not yet been allocated for this array.</P></td> + </tr> + + <tr> + <td>Size</td> + <td><P>This field contains the size allocated to store the raw data.</P></td> + </tr> + </table> + </div> + + <br> + <P>Class-specific information for chunked layout (Class 2): + + <br> + <div align=center> + <table class=format> + <caption> + Property Descriptions + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan=3 bgcolor=#DDDDDD> </td> + </tr> + + <tr> + <td colspan=4><br>Address<br><br></td> + </tr> + + <tr> + <td colspan=4>Dimension 0 (4-bytes)</td> + </tr> + + <tr> + <td colspan=4>Dimension 1 (4-bytes)</td> + </tr> + + <tr> + <td colspan=4>...</td> + </tr> + + <tr> + <td colspan=4>Dataset Element Size</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td><P>A chunk has a fixed dimensionality. This field specifies + the number of dimension size fields later in the message.</P></td> + </tr> + + <tr> + <td>Address</td> + <td><P>This is the address of the B-tree that is used to look up the addresses of the + chunks. The address may have the "undefined address" value, to indicate that + storage has not yet been allocated for this array.</P></td> + </tr> + + <tr> + <td>Dimensions</td> + <td><P>These values define the dimension size of a single chunk, in + units of array elements (not bytes). The first dimension stored in + the list of dimensions is the slowest changing dimension and the + last dimension stored is the fastest changing dimension. + </P> + </td> + </tr> + + <tr> + <td>Dataset Element Size</td> + <td><P>The size of a dataset element, in bytes. + </P> + </td> + </tr> + </table> + </div> + + <hr> + <h4><a name="ReservedMessage_0009">Name: Reserved - Not Assigned Yet</a></h4> + <P class=item><B>Header Message Type:</B> 0x0009</P> + <P class=item><B>Length:</B> N/A</P> + <P class=item><B>Status:</B> N/A</P> + <P class=item><B>Format of Data:</B> N/A</P> + + <P class=item><B>Purpose and Description:</B> This message type was skipped during the initial + specification of the file format and may be used in a future expansion to the format. + + <hr> + <h4><a name="ReservedMessage_000A">Name: Reserved - Not Assigned Yet</a></h4> + <P class=item><B>Header Message Type:</B> 0x0009</P> + <P class=item><B>Length:</B> N/A</P> + <P class=item><B>Status:</B> N/A</P> + <P class=item><B>Format of Data:</B> N/A</P> + + <P class=item><B>Purpose and Description:</B> This message type was skipped during the initial + specification of the file format and may be used in a future expansion to the format. + + <hr> + <h4><a name="FilterMessage">Name: Data Storage - Filter Pipeline</a></h4> + <P class=item><B>Header Message Type:</B> 0x000B</P> + <P class=item><B>Length:</B> varies</P> + <P class=item><B>Status:</B> Optional, may not be repeated.</P> + + <P class=item><B>Description:</B> This message describes the + filter pipeline which should be applied to the data stream by + providing filter identification numbers, flags, a name, and + client data.</P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Filter Pipeline Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan=2>Reserved</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4><br>Filter List<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number for this message. This document + describes version 1.</P></td> + </tr> + + <tr> + <td>Number of Filters</td> + <td><P>The total number of filters described by this + message. The maximum possible number of filters in a + message is 32.</P></td> + </tr> + + <tr> + <td>Filter List</td> + <td><P>A description of each filter. A filter description + appears in the next table.</P></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Filter Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=2>Filter Identification</td> + <td colspan=2>Name Length</td> + </tr> + + <tr> + <td colspan=2>Flags</td> + <td colspan=2>Number of Values for Client Data</td> + </tr> + + <tr> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Client Data<br><br></td> + </tr> + + <tr> + <td colspan=4>Padding</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Filter Identification</td> + <td> + <p> + This value, often referred to as a filter identifier, + is designed to be a unique identifier for the filter. + Values from zero through 32,767 are reserved for filters + supported by The HDF Group in the HDF5 library and for + filters requested and supported by third parties. + Filters supported by The HDF Group are documented immediately + below. Information on 3rd-party filters can be found at + <a href="/services/contributions.html#filters"> + <code>https://support.hdfgroup.org/services/contributions.html#filters</code></a>. + <a href="#Footnote1Change"><sup><small>1</small></sup></a> + <p> + To request a filter identifier, please contact + The HDF Group’s Help Desk at + <img src="Graphics/help.png" valign="center" height=14>. + You will be asked to provide the following information: + <ol> + <li>Contact information for the developer requesting the + new identifier + <li>A short description of the new filter + <li>Links to any relevant information, including licensing + information + </ol> + <p> + Values from 32768 to 65535 are reserved for non-distributed uses + (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range. + + <p> + The filters currently in library version 1.6.5 are + listed below: + <table class=list> + <tr> + <th width="30%">Identification</th> + <th align=left>Name</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align=center><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align=center><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + </table> + </P></td> + </tr> + + <tr> + <td>Name Length</td> + <td><P>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</P></td> + </tr> + + <tr> + <td>Flags</td> + <td><P>The flags indicate certain properties for a filter. The + bit values defined so far are:</P> + <table class=list> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>bit 1</code></td> + <td>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently removed from the pipeline.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Client Data Number of Values</td> + <td><P>Each filter can store a few integer values to control + how the filter operates. The number of entries in the + Client Data array is stored in this field.</P></td> + </tr> + + <tr> + <td>Name</td> + <td><P>If the Name Length field is non-zero then it will + contain the size of this field, a multiple of eight. This + field contains a null-terminated, ASCII character + string to serve as a comment/name for the filter.</P></td> + </tr> + + <tr> + <td>Client Data</td> + <td><P>This is an array of four-byte integers which will be + passed to the filter function. The Client Data Number of + Values determines the number of elements in the array.</P></td> + </tr> + + <tr> + <td>Padding</td> + <td><P>Four bytes of zeros are added to the message at this + point if the Client Data Number of Values field contains + an odd number.</P></td> + </tr> + </table> + </div> + <p> + <hr align="left" width="50"> + <a name="Footnote1Change"><sup>1</sup></a>If you are reading + an earlier version of this document, this link may have changed. + If the link does not work, use the latest version of this document + on <a href="https://support.hdfgroup.org">The HDF Group</a>’s website, + <a href="/HDF5/doc/H5.format.html"> + <code>https://support.hdfgroup.org/HDF5/doc/H5.format.html</code></a>; + the link there will always be correct. + <small><a href="#FilterMessage">(Return)</a> + </P> + + <hr> + <h4><a name="AttributeMessage">Name: Attribute</a></h4> + <P class=item><B>Header Message Type:</B> 0x000C + <P class=item><B>Length:</B> varies + <P class=item><B>Status:</B> Optional, may be repeated. + + <P class=item><B>Description:</B> The <em>Attribute</em> + message is used to list objects in the HDF file which are used + as attributes, or "metadata" about the current object. An + attribute is a small dataset; it has a name, a datatype, a data + space, and raw data. Since attributes are stored in the object + header they must be relatively small (<64KB) and can be + associated with any type of object which has an object header + (groups, datasets, named types and spaces, etc.). + + <P class=item2>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). Attributes on different objects may have the + same name, however. + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Attribute Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved</td> + <td colspan=2>Name Size</td> + </tr> + + <tr> + <td colspan=2>Datatype Size</td> + <td colspan=2>Dataspace Size</td> + </tr> + + <tr> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Datatype<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Dataspace<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Data<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number information is used for changes in the format of the + attribute message and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Used by the library before version 1.6 to encode attribute message. + This version does not support shared data type.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Reserved</td> + <td><P>This field is reserved for later use and is set to + zero.</P></td> + </tr> + + <tr> + <td>Name Size</td> + <td><P>The length of the attribute name in bytes including the + null terminator. Note that the Name field below may + contain additional padding not represented by this + field.</P></td> + </tr> + + <tr> + <td>Datatype Size</td> + <td><P>The length of the datatype description in the Datatype + field below. Note that the Datatype field may contain + additional padding not represented by this field.</P></td> + </tr> + + <tr> + <td>Dataspace Size</td> + <td><P>The length of the dataspace description in the Dataspace + field below. Note that the Dataspace field may contain + additional padding not represented by this field.</P></td> + </tr> + + <tr> + <td>Name</td> + <td><P>The null-terminated attribute name. This field is + padded with additional null characters to make it a + multiple of eight bytes.</P></td> + </tr> + + <tr> + <td>Datatype</td> + <td><P>The datatype description follows the same format as + described for the datatype object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</P></td> + </tr> + + <tr> + <td>Dataspace</td> + <td><P>The dataspace description follows the same format as + described for the dataspace object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</P></td> + </tr> + + <tr> + <td>Data</td> + <td><P>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. This + field is <em>not</em> padded with additional bytes.</P></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Attribute Message (Version 2) + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flag</td> + <td colspan=2>Name Size</td> + </tr> + + <tr> + <td colspan=2>Type Size</td> + <td colspan=2>Space Size</td> + </tr> + + <tr> + <td colspan=4><br>Name<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Type<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Space<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Data<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number information is used for changes in the format of the + attribute message and is described here:</P> + <table class=list width="90%"> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Used by the library of version 1.6.x and after to encode attribute message. + This version supports shared data type. The fields of name, type, and space + are not padded with additional bytes of zero.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Flag</td> + <td><P>This field indicates whether the data type of this attribute is shared:</P> + <table class=list width="90%"> + <tr> + <th width="30%">Value</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Datatype is <em>not</em> shared.</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Datatype is shared.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Name Size</td> + <td><P>The length of the attribute name in bytes including the + null terminator.</P></td> + </tr> + + <tr> + <td>Datatype Size</td> + <td><P>The length of the datatype description in the Datatype + field below.</P></td> + </tr> + + <tr> + <td>Dataspace Size</td> + <td><P>The length of the dataspace description in the Dataspace + field below.</P></td> + </tr> + + <tr> + <td>Name</td> + <td><P>The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes.</P></td> + </tr> + + <tr> + <td>Datatype</td> + <td><P>The datatype description follows the same format as + described for the datatype object header message. This + field is <em>not</em> padded with additional bytes.</P></td> + </tr> + + <tr> + <td>Dataspace</td> + <td><P>The dataspace description follows the same format as + described for the dataspace object header message. This + field is <em>not</em> padded with additional bytes.</P></td> + </tr> + + <tr> + <td>Data</td> + <td><P>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. This + field is <em>not</em> padded with additional zero + bytes.</P></td> + </tr> + </table> + </div> + + <hr> + <h4><a name="CommentMessage">Name: Object Comment</a></h4> + + <P class=item><B>Header Message Type:</B> 0x000D</P> + <P class=item><B>Length:</B> varies</P> + <P class=item><B>Status:</B> Optional, may not be repeated.</P> + + <P class=item><B>Description:</B> The object comment is + designed to be a short description of an object. An object comment + is a sequence of non-zero (<code>\0</code>) ASCII characters with no other + formatting included by the library.</P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Name Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4><br>Comment<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Name</td> + <td>A null terminated ASCII character string.</td> + </tr> + </table> + </div> + + <hr> + <h4><a name="OldModifiedMessage">Name: Object Modification Date & Time (Old)</a></h4> + + <P class=item><B>Header Message Type:</B> 0x000E</P> + <P class=item><B>Length:</B> fixed</P> + <P class=item><B>Status:</B> Optional, may not be repeated.</P> + + <P class=item><B>Description:</B> The object modification date + and time is a timestamp which indicates (using ISO-8601 date and + time format) the last modification of an object. The time is + updated when any object header message changes according to the + system clock where the change was posted. + + <br><br>This modification time message is deprecated in favor of the "new" + modification time message (Message Type 0x0012) and is no longer written + to the file in versions of the HDF5 library after the 1.6.0 version. + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Modification Time Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4>Year</td> + </tr> + + <tr> + <td colspan=2>Month</td> + <td colspan=2>Day of Month</td> + </tr> + + <tr> + <td colspan=2>Hour</td> + <td colspan=2>Minute</td> + </tr> + + <tr> + <td colspan=2>Second</td> + <td colspan=2>Reserved</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Year</td> + <td><P>The four-digit year as an ASCII string. For example, + <code>1998</code>. All fields of this message should be interpreted + as coordinated universal time (UTC)</P></td> + </tr> + + <tr> + <td>Month</td> + <td><P>The month number as a two digit ASCII string where + January is <code>01</code> and December is <code>12</code>.</P></td> + </tr> + + <tr> + <td>Day of Month</td> + <td><P>The day number within the month as a two digit ASCII + string. The first day of the month is <code>01</code>.</P></td> + </tr> + + <tr> + <td>Hour</td> + <td><P>The hour of the day as a two digit ASCII string where + midnight is <code>00</code> and 11:00pm is <code>23</code>.</P></td> + </tr> + + <tr> + <td>Minute</td> + <td><P>The minute of the hour as a two digit ASCII string where + the first minute of the hour is <code>00</code> and + the last is <code>59</code>.</P></td> + </tr> + + <tr> + <td>Second</td> + <td><P>The second of the minute as a two digit ASCII string + where the first second of the minute is <code>00</code> + and the last is <code>59</code>.</P></td> + </tr> + + <tr> + <td>Reserved</td> + <td><P>This field is reserved and should always be zero.</P></td> + </tr> + </table> + </div> + + <hr> + <h4><a name="SharedMessage">Name: Shared Object Message</a></h4> + <P class=item><B>Header Message Type:</B> 0x000F</P> + <P class=item><B>Length:</B> Fixed</P> + <P class=item><B>Status:</B> Optional, may be repeated.</P> + + <P class=item><B>Description:</B> A constant message can be shared among + several object headers. A <em>Shared Object</em> Message contains the address of + the object message to be shared. Care must be exercised to prevent cycles when a + message of one object header points to a message in some other object header. + Starting from Version 2 of the Shared Object Message, the <em>Flags</em> + field becomes unused. + </P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Shared Object Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan=2>Reserved</td> + </tr> + + <tr> + <td colspan=4>Reserved</td> + </tr> + + <tr> + <td colspan=4><br>Pointer<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number is used when there are changes in the format + of a shared object message and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Used by the library before version 1.6.1. In this version, + the Flags field is used to indicate whether the actual message is + stored in the global heap (never implemented). The Pointer field + either contains the the header message address in the global heap + (never implemented) or the address of the shared object header.</td> + </tr> + </table> + </tr> + + <tr> + <td>Flags</td> + <td><P>The Shared Message message points to a message which is + shared among multiple object headers. The Flags field + describes the type of sharing:</P> + <table class=list> + <tr> + <th width="30%">Bit</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>If this bit is clear then the actual message is the + first message in some other object header; otherwise + the actual message is stored in the global heap (never + implemented).</td> + </tr> + + <tr> + <td align=center><code>2-7</code></td> + <td>Reserved (always zero)</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Pointer</td> + <td><P>The address of the object header + containing the message to be shared.</P></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=format> + <caption> + Shared Object Message (Version 2) + </caption> + + <tr> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan=2 bgcolor=#DDDDDD> </td> + </tr> + + <tr> + <td colspan=4><br>Pointer<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number is used when there are changes in the format + of a shared object message and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>2</code></td> + <td>Used by the library of version 1.6.1 and after. In this version, + The Flags field is not used and the Pointer field contains the address + of the object header containing the message to be shared. </td> + </tr> + </table> + </tr> + + <tr> + <td>Flags</td> + <td><P>Unused.</P></td> + </tr> + + <tr> + <td>Pointer</td> + <td><P>The address of the object header + containing the message to be shared.</P></td> + </tr> + </table> + </div> + + + <hr> + <h4><a name="ContinuationMessage">Name: Object Header Continuation</a></h4> + <P class=item><B>Header Message Type:</B> 0x0010</P> + <P class=item><B>Length:</B> fixed</P> + <P class=item><B>Status:</B> Optional, may be repeated.</P> + <P class=item><B>Description:</B> The object header continuation is the location + in the file of more header messages for the current data object. This can be + used when header blocks become too large or are likely to change over time.</P> + + <P class=item><B>Format of Data:</B> + <br> + <div align=center> + <table class=format> + <caption> + Object Header Continuation Message + </caption> + + <tr> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + </tr> + + <tr> + <td colspan=4><br>Offset<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Length<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width=30%>Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Offset</td> + <td><P>This value is the offset in bytes from the beginning of the file where the + header continuation information is located.</P></td> + </tr> + + <tr> + <td>Length</td> + <td><P>This value is the length in bytes of the header continuation information in + the file.</P></td> + </tr> + </table> + </div> + + <hr> + <h4><a name="SymbolTableMessage">Name: Group Message</a></h4> + <P class=item><B>Header Message Type:</B> 0x0011</P> + <P class=item><B>Length:</B> fixed</P> + <P class=item><B>Status:</B> Required for groups, may not be repeated.</P> + <P class=item><B>Description:</B> Each group has a B-tree and a + name heap which are pointed to by this message.</P> + <P class=item><B>Format of data:</B> + + <br> + <div align=center> + <table class=format> + <caption> + <B>Group Message</B> + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan=4><br>B-tree Address<br><br></td> + </tr> + + <tr> + <td colspan=4><br>Heap Address<br><br></td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width=30%>Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>B-tree Address</td> + <td><P>This value is the offset in bytes from the beginning of the file + where the B-tree is located.</P></td> + </tr> + + <tr> + <td>Heap Address</td> + <td><P>This value is the offset in bytes from the beginning of the file + where the group name heap is located.</P></td> + </tr> + </table> + </div> + + <hr> + <h4><a name="ModifiedMessage">Name: Object Modification Date & Time</a></h4> + + <P class=item><B>Header Message Type:</B> 0x0012 </P> + <P class=item><B>Length:</B> Fixed </P> + <P class=item><B>Status:</B> Optional, may not be repeated. </P> + + <P class=item><B>Description:</B> The object modification date + and time is a timestamp which indicates the last modification of an object. + The time is updated when any object header message changes according to the + system clock where the change was posted. + </P> + + <P class=item><B>Format of Data:</B> + <div align=center> + <table class=format> + <caption> + Modification Time Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan=3>Reserved</td> + </tr> + + <tr> + <td colspan=4>Seconds After Epoch</td> + </tr> + </table> + </div> + + <br> + <div align=center> + <table class=desc> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td>Version</td> + <td><P>The version number is used for changes in the format of Object Modification Time + and is described here:</P> + <table class=list> + <tr> + <th width="30%">Version</th> + <th align=left>Description</th> + </tr> + + <tr> + <td align=center><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align=center><code>1</code></td> + <td>Used by Version 1.6.1 and after of the library to encode time. In + this version, the time is the seconds after Epoch.</td> + </tr> + </table> + </td> + </tr> + + <tr> + <td>Reserved</td> + <td><P>This field is reserved and should always be zero.</P></td> + </tr> + + <tr> + <td>Seconds After Epoch</td> + <td><P>The number of seconds since 0 hours, 0 minutes, 0 seconds, + January 1, 1970, Coordinated Universal Time.</P></td> + </tr> + </table> + </div> + +<hr> +<h3><a name="DataStorage">Disk Format: Level 2b - Data Object Data Storage</a></h3> +<P>The data for an object is stored separately from the header +information in the file and may not actually be located in the HDF5 file +itself if the header indicates that the data is stored externally. The +information for each record in the object is stored according to the +dimensionality of the object (indicated in the dimensionality header message). +Multi-dimensional data is stored in C order [same as current scheme], i.e. the +"last" dimension changes fastest. +<P>Data whose elements are composed of simple number-types are stored in +native-endian IEEE format, unless they are specifically defined as being stored +in a different machine format with the architecture-type information from the +number-type header message. This means that each architecture will need to +[potentially] byte-swap data values into the internal representation for that +particular machine. +<P> Data with a variable-length datatype is stored in the global heap +of the HDF5 file. Global heap identifiers are stored in the +data object storage. +<P>Data whose elements are composed of pointer number-types are stored in several +different ways depending on the particular pointer type involved. Simple +pointers are just stored as the dataset offset of the object being pointed to with the +size of the pointer being the same number of bytes as offsets in the file. +Dataset region references are stored as a heap-ID which points to the following +information within the file-heap: an offset of the object pointed to, number-type +information (same format as header message), dimensionality information (same +format as header message), sub-set start and end information (i.e. a coordinate +location for each), and field start and end names (i.e. a [pointer to the] +string indicating the first field included and a [pointer to the] string name +for the last field). + +<P>Data of a compound datatype is stored as a contiguous stream of the items +in the structure, with each item formatted according to its datatype.</p> + +<hr> +<h3><a name="Appendix">Appendix</a></h3> +<P>Definitions of various terms used in this document. +</P> +<P>The <A name="UndefinedAddress">"undefined address"</A> for a file is a +file address with all bits set, i.e. <code>0xffff...ff</code>. +<P>The <A name="UnlimitedDim">"unlimited size"</A> for a size is a +value with all bits set, i.e. <code>0xffff...ff</code>. + +</body> +</html> diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html new file mode 100644 index 0000000..3653489 --- /dev/null +++ b/doxygen/examples/H5.format.2.0.html @@ -0,0 +1,14902 @@ +<!DOCTYPE HTML> +<html> + <head> + <title> + HDF5 File Format Specification Version 2.0 + </title> + +<style> +h1 { display: block; + margin-top: 24px; + margin-bottom: 24px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + } + +h2 { display: block; + margin-top: 8x; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + } +<!-- A horizontal rule (<hr />) should be placed on the line above +each h2 tag. The h2 tags are used on the main sections along with +the hr tags. --> + +h3 { display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + } + +h4 { display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + } + +p { display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + } +<!-- +p.item { margin-left: 2em; + text-indent: -2em + } --> +<!-- p.item2 { margin-left: 2em; text-indent: 2em} --> + +table.format { border:solid; + border-collapse:collapse; + caption-side:top; + text-align:center; + width:80%; + } +table.format th { border:ridge; + padding:4px; + width:25%; + } +table.format td { border:ridge; + padding:4px; + } +table.format caption { font-weight:bold; + font-size:larger; + } + +table.note {border:none; + text-align:right; + width:80%; + } + +table.desc { border:solid; + border-collapse:collapse; + caption-size:top; + text-align:left; + width:80%; + } +table.desc tr { vertical-align:top; + } +table.desc th { border-style:ridge; + font-size:larger; + padding:4px; + <!-- text-decoration:underline; --> + } +table.desc td { border-style:ridge; + <!-- padding: 4px; --> + vertical-align:text-top; + } +table.desc caption { font-weight:bold; + font-size:larger; + } + +table.list { border:none; + width:100% + } +table.list tr { vertical-align:text-top; + } +table.list th { border:none; + text-decoration:underline; + vertical-align:text-top; + } +table.list td { border:none; + vertical-align:text-top; + } + +table.msgdesc { border:none; + text-align:left; + width: 80% + } +table.msgdesc tr { vertical-align:text-top; + border-spacing:0; + padding:0; } +table.msgdesc th { border:none; + text-decoration:underline; + vertical-align:text-top; } +table.msgdesc td { border:none; + vertical-align:text-top; + } + +table.list80 { border:none; + width:80% + } +table.list80 tr { vertical-align:text-top; + } +table.list80 th { border:none; + text-decoration:underline; + vertical-align:text-top; + } +table.list80 td { border:none; + vertical-align:text-top; + } + +table.glossary { border:none; + text-align:left; + width: 80% + } +table.glossary tr { vertical-align:text-top; + border-spacing:0; + padding:0; } +table.glossary th { border:none; + text-align:left; + text-decoration:underline; + vertical-align:text-top; } +table.glossary td { border:none; + text-align:left; + vertical-align:text-top; + } + +div { page-break-inside:avoid; + page-break-after:auto + } + +</style> + + <center> + <table border="0" width="90%"> + <tr> + <td valign="top"> + <ol type="I"> + <li><a href="#Intro">Introduction</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ThisDocument">This Document</a></li> + <li><a href="#ChangesForHdf5_1_10">Changes for HDF5 1.10</a></li> + </ol> + </font> + + <li><a href="#FileMetaData">Disk Format: Level 0 - File Metadata</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Superblock">Disk Format: Level 0A - Format Signature and Superblock</a></li> + <li><a href="#DriverInfo">Disk Format: Level 0B - File Driver Info</a></li> + <li><a href="#SuperblockExt">Disk Format: Level 0C - Superblock Extension</a></li> + </ol> + </font> + <li><a href="#FileInfra">Disk Format: Level 1 - File Infrastructure</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Btrees">Disk Format: Level 1A - B-trees and B-tree + Nodes</a></li> + <ol type="1"> + <li><a href="#V1Btrees">Disk Format: Level 1A1 - Version 1 + B-trees (B-link Trees)</a></li> + <li><a href="#V2Btrees">Disk Format: Level 1A2 - Version 2 + B-trees</a></li> + </ol> + <li><a href="#SymbolTable">Disk Format: Level 1B - Group Symbol Table Nodes</a></li> + <li><a href="#SymbolTableEntry">Disk Format: Level 1C - Symbol Table Entry</a></li> + <li><a href="#LocalHeap">Disk Format: Level 1D - Local Heaps</a></li> + <li><a href="#GlobalHeap">Disk Format: Level 1E - Global Heap</a></li> + <li><a href="#FractalHeap">Disk Format: Level 1F - Fractal Heap</a></li> + <li><a href="#FreeSpaceManager">Disk Format: Level 1G - Free-space Manager</a></li> + <li><a href="#SOHMTable">Disk Format: Level 1H - Shared Object Header Message Table</a></li> + </ol> + </font> + <li><a href="#DataObject">Disk Format: Level 2 - Data Objects</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object Headers</a></li> + <ol type="1"> + <li><a href="#ObjectHeaderPrefix">Disk Format: Level 2A1 - Data Object Header Prefix</a></li> + <ol type="a"> + <li><a href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix</a></li> + <li><a href="#V2ObjectHeaderPrefix">Version 2 Data Object Header Prefix</a></li> + </ol> + <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - Data Object Header Messages</a></li> + <ol type="a"> + <li><a href="#NILMessage">The NIL Message</a></li> <!-- 0x0000 --> + <li><a href="#DataspaceMessage">The Dataspace Message</a></li> <!-- 0x0001 --> + <li><a href="#LinkInfoMessage">The Link Info Message</a></li> <!-- 0x0002 --> + </ol> + </ol> + </ol> + </font> + </ol> + </td> + + <td> </td> + + <td valign="top"> + <ol type="I" start="4"> + <li><a href="#DataObject">Disk Format: Level 2 - Data + Objects</a><font size="-1"><i> (Continued)</i></li> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object + Headers</a><i> (Continued)</i></li> + <ol type="1" start="2"> + <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - + Data Object Header Messages</a><i> (Continued)</i></li> + <ol type="a" start="4"> + <li><a href="#DatatypeMessage">The Datatype Message</a></li> <!-- 0x0003 --> + <li><a href="#OldFillValueMessage">The Data Storage - + Fill Value (Old) Message</a></li> <!-- 0x0004 --> + <li><a href="#FillValueMessage">The Data Storage - + Fill Value Message</a></li> <!-- 0x0005 --> + <li><a href="#LinkMessage">The Link Message</a></li> <!-- 0x0006 --> + <li><a href="#ExternalFileListMessage">The Data Storage - + External Data Files Message</a></li> <!-- 0x0007 --> + <li><a href="#LayoutMessage">The Data Storage - + Layout Message</a></li> <!-- 0x0008 --> + <li><a href="#BogusMessage">The Bogus Message</a></li> <!-- 0x0009 --> + <li><a href="#GroupInfoMessage">The Group Info + Message</a></li> <!-- 0x000a --> + <li><a href="#FilterMessage">The Data Storage - + Filter Pipeline Message</a></li> <!-- 0x000b --> + <li><a href="#AttributeMessage">The Attribute + Message</a></li> <!-- 0x000c --> + <li><a href="#CommentMessage">The Object Comment + Message</a></li> <!-- 0x000d --> + <li><a href="#OldModificationTimeMessage">The Object + Modification Time (Old) Message</a></li> <!-- 0x000e --> + <li><a href="#SOHMTableMessage">The Shared Message + Table Message</a></li> <!-- 0x000f --> + <li><a href="#ContinuationMessage">The Object Header + Continuation Message</a></li> <!-- 0x0010 --> + <li><a href="#SymbolTableMessage">The Symbol + Table Message</a></li> <!-- 0x0011 --> + <li><a href="#ModificationTimeMessage">The Object + Modification Time Message</a></li> <!-- 0x0012 --> + <li><a href="#BtreeKValuesMessage">The B-tree + ‘K’ Values Message</a></li> <!-- 0x0013 --> + <li><a href="#DrvInfoMessage">The Driver Info + Message</a></li> <!-- 0x0014 --> + <li><a href="#AinfoMessage">The Attribute Info + Message</a></li> <!-- 0x0015 --> + <li><a href="#RefCountMessage">The Object Reference + Count Message</a></li> <!-- 0x0016 --> + <li><a href="#FsinfoMessage">The File Space Info + Message</a></li> <!-- 0x0018 --> + </ol> + </ol> + <li><a href="#DataStorage">Disk Format: Level 2B - Data Object Data Storage</a></li> + </ol> + </font> + <li><a href="#AppendixA">Appendix A: Definitions</a></li> + <li><a href="#AppendixB">Appendix B: File Memory Allocation Types</a></li> + </ol> +</td></tr> +</table> +</center> + + + +<br /> +<br /> +<hr /> +<a name="Intro"><h2>I. Introduction</h2></a> + + <table align="right" width="100"> + <tr><td> </td><td align="center"> + <hr /> + <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace="15" vspace="15"> + </td><td> </td></tr> + <tr><td> </td><td align="center"> + <strong>Figure 1:</strong> Relationships among the HDF5 root group, other groups, and objects + <hr /> + </td><td> </td></tr> + + <tr><td> </td><td align="center"> + <img src="FF-IH_FileObject.gif" alt="HDF5 Objects" hspace="15" vspace="15"> + </td><td> </td></tr> + <tr><td> </td><td align="center"> + <strong>Figure 2:</strong> HDF5 objects -- datasets, datatypes, or dataspaces + <hr /> + </td><td> </td></tr> + </table> + + + <p>The format of an HDF5 file on disk encompasses several + key ideas of the HDF4 and AIO file formats as well as + addressing some shortcomings therein. The new format is + more self-describing than the HDF4 format and is more + uniformly applied to data objects in the file.</p> + + <p>An HDF5 file appears to the user as a directed graph. + The nodes of this graph are the higher-level HDF5 objects + that are exposed by the HDF5 APIs:</p> + + <ul> + <li>Groups</li> + <li>Datasets</li> + <li>Committed (formerly Named) datatypes</li> + </ul> + + <p>At the lowest level, as information is actually written to the disk, + an HDF5 file is made up of the following objects:</p> + <ul> + <li>A superblock</li> + <li>B-tree nodes</li> + <li>Heap blocks</li> + <li>Object headers</li> + <li>Object data</li> + <li>Free space</li> + </ul> + + <p>The HDF5 Library uses these low-level objects to represent the + higher-level objects that are then presented to the user or + to applications through the APIs. For instance, a group is an + object header that contains a message that points to a local + heap (for storing the links to objects in the group) and to a + B-tree (which indexes the links). A dataset is an object header + that contains messages that describe datatype, dataspace, layout, + filters, external files, fill value, and other elements with the + layout message pointing to either a raw data chunk or to a + B-tree that points to raw data chunks.</p> + + +<br /> +<a name="ThisDocument"><h3>I.A. This Document</h3></a> + + <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> + + <p>Three levels of information comprise the file format. + Level 0 contains basic information for identifying and + defining information about the file. Level 1 information contains + the information about the pieces of a file shared by many objects + in the file (such as a B-trees and heaps). Level 2 is the rest + of the file and contains all of the data objects, with each object + partitioned into header information, also known as + <em>metadata</em>, and data.</p> + + <p>The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans + in the table. There are three exceptions: (1) The size may be + overridden by specifying a size in parentheses, (2) the size of + addresses is determined by the <em>Size of Offsets</em> field + in the superblock and is indicated in this document with a + superscripted ‘O’, and (3) the size of length fields is determined + by the <em>Size of Lengths</em> field in the superblock and is + indicated in this document with a superscripted ‘L’.</p> + + <p>Values for all fields in this document should be treated as unsigned + integers, unless otherwise noted in the description of a field. + Additionally, all metadata fields are stored in little-endian byte + order. + </p> + + <p>All checksums used in the format are computed with the + <a href="http://www.burtleburtle.net/bob/hash/doobs.html">Jenkins’ + lookup3</a> algorithm. + </p> + + <p>Whenever a bit flag or field is mentioned for an entry, bits are + numbered from the lowest bit position in the entry. + </p> + + <p>Various tables in this document aligned with “This space inserted + only to align table nicely”. These entries in the table are just + to make the table presentation nicer and do not represent any values + or padding in the file. + </p> + + +<br /> +<a name="ChangesForHdf5_1_10"><h3>I.B. Changes for HDF5 1.10</h3></a> + + <p>As of October 2015, changes in the file format for HDF5 1.10 + have not yet been finalized.</p> + + + +<br /> +<br /> +<hr /> +<h2><a name="FileMetaData"> +II. Disk Format: Level 0 - File Metadata</a></h2> + +<br /> +<h3><a name="Superblock"> +II.A. Disk Format: Level 0A - Format Signature and Superblock</a></h3> + + <p>The superblock may begin at certain predefined offsets within + the HDF5 file, allowing a block of unspecified content for + users to place additional information at the beginning (and + end) of the HDF5 file without limiting the HDF5 Library’s + ability to manage the objects within the file itself. This + feature was designed to accommodate wrapping an HDF5 file in + another file format or adding descriptive information to an HDF5 + file without requiring the modification of the actual file’s + information. The superblock is located by searching for the + HDF5 format signature at byte offset 0, byte offset 512, and at + successive locations in the file, each a multiple of two of + the previous location; in other words, at these byte offsets: + 0, 512, 1024, 2048, and so on.</p> + + <p>The superblock is composed of the format signature, followed by a + superblock version number and information that is specific to each + version of the superblock. + Currently, there are three versions of the superblock format. + Version 0 is the default format, while version 1 is basically the same + as version 0 with additional information when a non-default B-tree ‘K’ + value is stored. Version 2 is the latest format, with some fields + eliminated or compressed and with superblock extension and checksum + support.</p> + + <p>Version 0 and 1 of the superblock are described below:</p> + + + <div align="center"> + <table class="format"> + <caption> + Superblock (Versions 0 and 1) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Format Signature (8 bytes)<br /><br /></td> + </tr> + + <tr> + <td>Version # of Superblock</td> + <td>Version # of File’s Free Space Storage</td> + <td>Version # of Root Group Symbol Table Entry</td> + <td>Reserved (zero)</td> + </tr> + + <tr> + <td>Version # of Shared Header Message Format</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>Reserved (zero)</td> + </tr> + + <tr> + <td colspan="2">Group Leaf Node K</td> + <td colspan="2">Group Internal Node K</td> + </tr> + + <tr> + <td colspan="4">File Consistency Flags</td> + </tr> + + <tr> + <td colspan="2" style="border:dotted;">Indexed Storage Internal Node K<sup>1</sup></td> + <td colspan="2" style="border:dotted;">Reserved (zero)<sup>1</sup></td> + </tr> + + <tr> + <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of File Free space Info<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Driver Information Block Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Root Group Symbol Table Entry</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in “Size of Offsets.”) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with a ‘1’ in the above table are + new in version 1 of the superblock) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td><p>This field contains a constant value and can be used to + quickly identify a file as being an HDF5 file. The + constant value is designed to allow easy identification of + an HDF5 file and to allow certain types of data corruption + to be detected. The file signature of an HDF5 file always + contains the following values:</p> + <center> + <table border align="center" cellpadding="4"> + <tr align="center"> + <td align="right">Decimal:</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align="center"> + <td align="right">Hexadecimal:</td> + <td>89</td> + <td>48</td> + <td>44</td> + <td>46</td> + <td>0d</td> + <td>0a</td> + <td>1a</td> + <td>0a</td> + </tr> + + <tr align="center"> + <td align="right">ASCII C Notation:</td> + <td>\211</td> + <td>H</td> + <td>D</td> + <td>F</td> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + </table> + </center> + <p>This signature both identifies the file as an HDF5 file + and provides for immediate detection of common + file-transfer problems. The first two bytes distinguish + HDF5 files on systems that expect the first two bytes to + identify the file type uniquely. The first byte is + chosen as a non-ASCII value to reduce the probability + that a text file may be misrecognized as an HDF5 file; + also, it catches bad file transfers that clear bit + 7. Bytes two through four name the format. The CR-LF + sequence catches bad file transfers that alter newline + sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse + of the CR-LF translation problem. (This is a direct + descendent of the + <a href="http://www.libpng.org/pub/png/spec/iso/index-object.html#5PNG-file-signature">PNG</a> file + signature.)</p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p></td> + </tr> + + <tr> + <td><p>Version Number of the Superblock</p></td> + <td><p>This value is used to determine the format of the + information in the superblock. When the format of the + information in the superblock is changed, the version number + is incremented to the next integer and can be used to + determine how the information in the superblock is + formatted.</p> + + <p>Values of 0, 1 and 2 are defined for this field. (The format + of version 2 is described below, not here) + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Version Number of the File’s Free Space + Information</p></td> + <td> + <p>This value is used to determine the format of the + file’s free space information. + </p> + <p>The only value currently valid in this field is ‘0’, which + indicates that the file’s free space is as described + <a href="#FreeSpaceManager">below</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Root Group Symbol Table + Entry</p></td> + <td><p>This value is used to determine the format of the + information in the Root Group Symbol Table Entry. When the + format of the information in that field is changed, the + version number is incremented to the next integer and can be + used to determine how the information in the field + is formatted.</p> + <p>The only value currently valid in this field is ‘0’, + which indicates that the root group symbol table entry is + formatted as described <a href="#SymbolTableEntry">below</a>.</p> + <p><em>This field is present in version 0 and 1 of the + superblock.</em></p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Shared Header Message Format</p></td> + <td><p>This value is used to determine the format of the + information in a shared object header message. Since the format + of the shared header messages differs from the other private + header messages, a version number is used to identify changes + in the format. + </p> + <p>The only value currently valid in this field is ‘0’, which + indicates that shared header messages are formatted as + described <a href="#ObjectHeaderMessages">below</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Size of Offsets</p></td> + <td><p>This value contains the number of bytes used to store + addresses in the file. The values for the addresses of + objects in the file are offsets relative to a base address, + usually the address of the superblock signature. This + allows a wrapper to be added after the file is created + without invalidating the internal offset locations. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Size of Lengths</p></td> + <td><p>This value contains the number of bytes used to store + the size of an object. + </p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Group Leaf Node K</p></td> + <td> + <p>Each leaf node of a group B-tree will have at + least this many entries but not more than twice this + many. If a group has a single leaf node then it + may have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Group Internal Node K</p></td> + <td> + <p>Each internal node of a group B-tree will have at + least this many entries but not more than twice this + many. If the group has only one internal + node then it might have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>File Consistency Flags</p></td> + <td> + <p>This value contains flags to indicate information + about the consistency of the information contained + within the file. Currently, the following bit flags are + defined: + <ul> + <li>Bit 0 set indicates that the file is opened for + write-access.</li> + <li>Bit 1 set indicates that the file has + been verified for consistency and is guaranteed to be + consistent with the format defined in this document.</li> + <li>Bits 2-31 are reserved for future use.</li> + </ul> + Bit 0 should be + set as the first action when a file is opened for write + access and should be cleared only as the final action + when closing a file. Bit 1 should be cleared during + normal access to a file and only set after the file’s + consistency is guaranteed by the library or a + consistency utility. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td> + <p>Each internal node of an indexed storage B-tree will have at + least this many entries but not more than twice this + many. If the index storage B-tree has only one internal + node then it might have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This is the absolute file address of the first byte of + the HDF5 data within the file. The library currently + constrains this value to be the absolute file address + of the superblock itself when creating new files; + future versions of the library may provide greater + flexibility. When opening an existing file and this address does + not match the offset of the superblock, the library assumes + that the entire contents of the HDF5 file have been adjusted in + the file and adjusts the base address and end of file address to + reflect their new positions in the file. Unless otherwise noted, + all other file addresses are relative to this base + address. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Address of Global Free-space Index</p></td> + <td> + <p>The file’s free space is not persistent for version 0 and 1 of + the superblock. + Currently this field always contains the + <a href="#UndefinedAddress">undefined address</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This is the absolute file address of the first byte past + the end of all HDF5 data. It is used to determine whether a + file has been accidently truncated and as an address where + file data allocation can occur if space from the free list is + not used. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Block Address</p></td> + <td> + <p>This is the relative file address of the file driver + information block which contains driver-specific + information needed to reopen the file. If there is no + driver information block then this entry should be the + <a href="#UndefinedAddress">undefined address</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Root Group Symbol Table Entry</p></td> + <td> + <p>This is the <a href="#SymbolTableEntry">symbol table entry</a> + of the root group, which serves as the entry point into + the group graph for the file. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + </table> + </div> + + <br /> + <p>Version 2 of the superblock is described below:</p> + + <div align="center"> + <table class="format"> + <caption> + Superblock (Version 2) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Format Signature (8 bytes)<br /><br /></td> + </tr> + + <tr> + <td>Version # of Superblock</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>File Consistency Flags</td> + </tr> + + <tr> + <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Superblock Extension Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Root Group Object Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Superblock Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in “Size of Offsets.”) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p></td> + </tr> + + <tr> + <td><p>Version Number of the Superblock</p></td> + <td> + <p>This field has a value of 2 and has the same meaning as for + versions 0 and 1. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Offsets</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Lengths</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>File Consistency Flags</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 except + that it is smaller (the number of reserved bits has been reduced + from 30 to 6). + </p> + </td> + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Superblock Extension Address</p></td> + <td> + <p>The field is the address of the object header for the + <a href="#SuperblockExt">superblock extension</a>. + If there is no extension then this entry should be the + <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Root Group Object Header Address</p></td> + <td> + <p>This is the address of + the <a href="#DataObject">root group object header</a>, + which serves as the entry point into the group graph for the file. + </p> + </td> + </tr> + + <tr> + <td><p>Superblock Checksum</p></td> + <td> + <p>The checksum for the superblock. + </p> + </td> + </tr> + + </table> + </div> + +<br /> +<h3><a name="DriverInfo"> +II.B. Disk Format: Level 0B - File Driver Info</a></h3> + + <p>The <b>driver information block</b> is an optional region of the + file which contains information needed by the file driver + to reopen a file. The format is described below:</p> + + + <div align="center"> + <table class="format"> + <caption> + Driver Information Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved</td> + </tr> + + <tr> + <td colspan="4">Driver Information Size</td> + </tr> + + <tr> + <td colspan="4"><br />Driver Identification (8 bytes)<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Driver Information (<em>variable size</em>)<br /><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number of the Driver Information Block. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td> + <p>The size in bytes of the <em>Driver Information</em> field. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td> + <p>This is an eight-byte ASCII string without null + termination which identifies the driver and/or version number + of the Driver Information Block. The predefined driver encoded + in this field by the HDF5 Library is identified by the + letters <code>NCSA</code> followed by the first four characters of + the driver name. If the Driver Information block is not + the original version then the last letter(s) of the + identification will be replaced by a version number in + ASCII, starting with 0. + </p> + <p> + Identification for user-defined drivers is also eight-byte long. + It can be arbitrary but should be unique to avoid + the four character prefix “NCSA”. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Driver Information</p></td> + <td>Driver information is stored in a format defined by the + file driver (see description below).</td> + </tr> + </table> + </div> + + <br /> + The two drivers encoded in the <em>Driver Identification</em> field are as follows: + <ul> + <li> + Multi driver: + <p> + The identifier for this driver is “NCSAmulti”. + This driver provides a mechanism for segregating raw data and different types of metadata + into multiple files. + These files are viewed by the library as a single virtual HDF5 file with a single file address. + A maximum of 6 files will be created for the following data: + superblock, B-tree, raw data, global heap, local heap, and object header. + More than one type of data can be written to the same file. + </p></li> + <li> + Family driver + <p> + The identifier for this driver is “NCSAfami” and is encoded in this field for library version 1.8 and after. + This driver is designed for systems that do not support files larger than 2 gigabytes + by splitting the HDF5 file address space across several smaller files. + It does nothing to segregate metadata and raw data; + they are mixed in the address space just as they would be in a single contiguous file. + </p></li> + </ul> + <p>The format of the <em>Driver Information</em> field for the + above two drivers are described below:</p> + + <div align="center"> + <table class="format"> + <caption> + Multi Driver Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Reserved</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File N<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File N<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 1 <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 2 <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File N <em>(variable size)</em><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Member Mapping</p></td> + <td><p>These fields are integer values from 1 to 6 + indicating how the data can be mapped to or merged with another type of + data. + <table class="list"> + <tr> + <th width="20%" align="center">Member Mapping</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">1</td> + <td>The superblock data.</td> + </tr> + <tr> + <td align="center">2</td> + <td>The B-tree data.</td> + </tr> + <tr> + <td align="center">3</td> + <td>The raw data.</td> + </tr> + <tr> + <td align="center">4</td> + <td>The global heap data.</td> + </tr> + <tr> + <td align="center">5</td> + <td>The local heap data.</td> + </tr> + <tr> + <td align="center">6</td> + <td>The object header data.</td> + </tr> + </table></p> + <p>For example, if the third field has the value 3 and all the rest have the + value 1, it means there are two files: one for raw data, and one for superblock, + B-tree, global heap, local heap, and object header.</p> + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td><p>These fields are reserved and should always be zero.</p></td> + </tr> + + <tr> + <td><p>Address of Member File N</p></td> + <td><p>This field Specifies the virtual address at which the member file starts.</p> + <p>N is the number of member files.</p> + </td> + </tr> + + <tr> + <td><p>End of Address for Member File N</p></td> + <td><p>This field is the end of the allocated address for the member file. + </p></td> + </tr> + + <tr> + <td><p>Name of Member File N</p></td> + <td><p>This field is the null-terminated name of the member file and + its length should be multiples of 8 bytes. + Additional bytes will be padded with <em>NULL</em>s. The default naming + convention is <em>%s-X.h5</em>, where <em>X</em> is one of the letters + <em>s</em> (for superblock), <em>b</em> (for B-tree), <em>r</em> (for raw data), + <em>g</em> (for global heap), <em>l</em> (for local heap), and <em>o</em> (for + object header). The name of the whole HDF5 file will substitute the <em>%s</em> + in the string. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Family Driver Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="8"><br />Size of Member File<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size of Member File</p></td> + <td><p>This field is the size of the member file in the family of files.</p></td> + </tr> + </table> + </div> + +<br /> +<h3><a name="SuperblockExt"> +II.C. Disk Format: Level 0C - Superblock Extension</a></h3> + + <p>The <em>superblock extension</em> is used to store superblock metadata + which is either optional, or added after the version of the superblock + was defined. Superblock extensions may only exist when version 2+ of + superblock is used. A superblock extension is an object header which may + hold the following messages:</p> + <ul> + <li> + <a href="#SOHMTableMessage">Shared Message Table message</a> containing + information to locate the master table of shared object header message + indices.</li> + <li> + <a href="#BtreeKValuesMessage">B-tree ‘K’ Values message</a> containing + non-default B-tree ‘K’ values.</li> + <li> + <a href="#DrvInfoMessage">Driver Info message</a> containing information + needed by the file driver in order to reopen a file. + See also the + <a href="#DriverInfo">“Disk Format: Level 0B - File Driver + Info”</a> section above.</li> + <li> + <a href="#FsinfoMessage">File Space Info message</a> containing + information about file space handling in the file.</li> + </ul> + + + +<br /> +<br /> +<hr /> +<h2><a name="FileInfra"> +III. Disk Format: Level 1 - File Infrastructure</a></h2> + +<br /> +<h3><a name="Btrees"> +III.A. Disk Format: Level 1A - B-trees and B-tree Nodes</a></h3> + + <p>B-trees allow flexible storage for objects which tend to grow + in ways that cause the object to be stored discontiguously. B-trees + are described in various algorithms books including “Introduction to + Algorithms” by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. B-trees are used in several places in the HDF5 file format, + when an index is needed for another data structure.</p> + + <p>The version 1 B-tree structure described below is the original index + structure, but are limited by some bugs in our implementation (mainly in + how they handle deleting records). The version 1 B-trees are being phased + out in favor of the version 2 B-trees described below, although both + types of structures may be found in the same file, depending on + application settings when creating the file.</p> + +<br /> +<h4><a name="V1Btrees"> +III.A.1. Disk Format: Level 1A1 - Version 1 B-trees (B-link Trees)</a></h4> + + <p>Version 1 B-trees in HDF5 files an implementation of the B-link tree, + in which the sibling nodes at a particular level in the tree are stored + in a doubly-linked list, is described in the “Efficient Locking for + Concurrent Operations on B-trees” paper by Phillip Lehman and S. Bing Yao + as published in the <cite>ACM Transactions on Database Systems</cite>, + Vol. 6, No. 4, December 1981.</p> + + <p>The B-link trees implemented by the file format contain one more + key than the number of children. In other words, each child + pointer out of a B-tree node has a left key and a right key. + The pointers out of internal nodes point to sub-trees while + the pointers out of leaf nodes point to symbol nodes and + raw data chunks. + Aside from that difference, internal nodes and leaf nodes + are identical.</p> + + <div align="center"> + <table class="format"> + <caption> + B-link Tree Nodes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Node Type</td> + <td>Node Level</td> + <td colspan="2">Entries Used</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Left Sibling<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Right Sibling<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 0 (variable size)</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 0<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 1 (variable size)</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 1<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Key 2<em>K</em> (variable size)</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 2<em>K</em><sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 2<em>K</em>+1 (variable size)</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>TREE</code>” is + used to indicate the + beginning of a B-link tree node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Node Type</p></td> + <td> + <p>Each B-link tree points to a particular type of data. + This field indicates the type of data as well as + implying the maximum degree <em>K</em> of the tree and + the size of each Key field. + + + <table class="list"> + <tr> + <th width="20%" align="center">Node Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>This tree points to group nodes.</td> + </tr> + <tr> + <td align="center">1</td> + <td>This tree points to raw data chunk nodes.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Node Level</p></td> + <td> + <p>The node level indicates the level at which this node + appears in the tree (leaf nodes are at level zero). Not + only does the level indicate whether child pointers + point to sub-trees or to data, but it can also be used + to help file consistency checking utilities reconstruct + damaged trees. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Entries Used</p></td> + <td> + <p>This determines the number of children to which this + node points. All nodes of a particular type of tree + have the same maximum degree, but most nodes will point + to less than that number of children. The valid child + pointers and keys appear at the beginning of the node + and the unused pointers and keys appear at the end of + the node. The unused pointers and keys have undefined + values. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Address of Left Sibling</p></td> + <td> + <p>This is the relative file address of the left sibling of + the current node. If the current + node is the left-most node at this level then this field + is the <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Address of Right Sibling</p></td> + <td> + <p>This is the relative file address of the right sibling of + the current node. If the current + node is the right-most node at this level then this + field is the <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Keys and Child Pointers</p></td> + <td> + <p>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> + child pointers interleaved between the keys. The number + of keys and child pointers actually containing valid + values is determined by the node’s <em>Entries Used</em> field. + If that field is <em>N</em> then the B-link tree contains + <em>N</em> child pointers and <em>N</em>+1 keys. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Key</p></td> + <td> + <p>The format and size of the key values is determined by + the type of data to which this tree points. The keys are + ordered and are boundaries for the contents of the child + pointer; that is, the key values represented by child + <em>N</em> fall between Key <em>N</em> and Key + <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the + tree points. + </p> + + <p> + The format of the key depends on the node type. + For nodes of node type 0 (group nodes), the key is formatted as + follows: + + <table class="list"> + <tr> + <td width="20%">A single field of <i>Size of Lengths</i> + bytes:</td> + <td width="80%">Indicates the byte offset into the local heap + for the first object name in the subtree which + that key describes. + </td> + </tr> + </table> + </p> + + + <p> + For nodes of node type 1 (chunked raw data nodes), the key is + formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-4:</td> + <td width="80%">Size of chunk in bytes.</td> + </tr> + <tr> + <td>Bytes 4-8:</td> + <td>Filter mask, a 32-bit bit field indicating which + filters have been skipped for this chunk. Each filter + has an index number in the pipeline (starting at 0, with + the first filter to apply) and if that filter is skipped, + the bit corresponding to its index is set.</td> + </tr> + <tr> + <td>(<em>D + 1</em>) 64-bit fields:</td> + <td>The offset of the + chunk within the dataset where <i>D</i> is the number + of dimensions of the dataset, and the last value is the + offset within the dataset’s datatype and should always be + zero. For example, if + a chunk in a 3-dimensional dataset begins at the + position <code>[5,5,5]</code>, there will be three + such 64-bit values, each with the value of + <code>5</code>, followed by a <code>0</code> value.</td> + </tr> + </table> + </p> + + </td> + </tr> + + <tr valign="top"> + <td><p>Child Pointer</p></td> + <td> + <p>The tree node contains file addresses of subtrees or + data depending on the node level. Nodes at Level 0 point + to data addresses, either raw data chunks or group nodes. + Nodes at non-zero levels point to other nodes of the + same B-tree. + </p> + <p>For raw data chunk nodes, the child pointer is the address + of a single raw data chunk. For group nodes, the child pointer + points to a <a href="#SymbolTable">symbol table</a>, which contains + information for multiple symbol table entries. + </p> + </td> + </tr> + </table> + </div> + + <p> + Conceptually, each B-tree node looks like this:</p> + <center> + <table> + <tr valign="top" align="center"> + <td>key[0]</td><td> </td> + <td>child[0]</td><td> </td> + <td>key[1]</td><td> </td> + <td>child[1]</td><td> </td> + <td>key[2]</td><td> </td> + <td>...</td><td> </td> + <td>...</td><td> </td> + <td>key[<i>N</i>-1]</td><td> </td> + <td>child[<i>N</i>-1]</td><td> </td> + <td>key[<i>N</i>]</td> + </tr> + </table> + </center> + <br /> + + where child[<i>i</i>] is a pointer to a sub-tree (at a level + above Level 0) or to data (at Level 0). + Each key[<i>i</i>] describes an <i>item</i> stored by the B-tree + (a chunk or an object of a group node). The range of values + represented by child[<i>i</i>] is indicated by key[<i>i</i>] + and key[<i>i</i>+1]. + + + <p>The following question must next be answered: + “Is the value described by key[<i>i</i>] contained in + child[<i>i</i>-1] or in child[<i>i</i>]?” + The answer depends on the type of tree. + In trees for groups (node type 0) the object described by + key[<i>i</i>] is the greatest object contained in + child[<i>i</i>-1] while in chunk trees (node type 1) the + chunk described by key[<i>i</i>] is the least chunk in + child[<i>i</i>].</p> + + <p>That means that key[0] for group trees is sometimes unused; + it points to offset zero in the heap, which is always the + empty string and compares as “less-than” any valid object name.</p> + + <p>And key[<i>N</i>] for chunk trees is sometimes unused; + it contains a chunk offset which compares as “greater-than” + any other chunk offset and has a chunk byte size of zero + to indicate that it is not actually allocated.</p> + +<br /> +<h4><a name="V2Btrees"> +III.A.2. Disk Format: Level 1A2 - Version 2 B-trees</a></h4> + + <p>Version 2 B-trees are “traditional” B-trees, with one major difference. + Instead of just using a simple pointer (or address in the file) to a + child of an internal node, the pointer to the child node contains two + additional pieces of information: the number of records in the child + node itself, and the total number of records in the child node and + all its descendants. Storing this additional information allows fast + array-like indexing to locate the n<sup>th</sup> record in the B-tree.</p> + + <p>The entry into a version 2 B-tree is a header which contains global + information about the structure of the B-tree. The <em>root node + address</em> + field in the header points to the B-tree root node, which is either an + internal or leaf node, depending on the value in the header’s + <em>depth</em> field. An internal node consists of records plus + pointers to further leaf or internal nodes in the tree. A leaf node + consists of solely of records. The format of the records depends on + the B-tree type (stored in the header).</p> + + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Node Size</td> + </tr> + <tr> + <td colspan="2">Record Size</td> + <td colspan="2">Depth</td> + </tr> + <tr> + <td>Split Percent</td> + <td>Merge Percent</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Root Node Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="2">Number of Records in Root Node</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records in B-tree<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTHD</code>” is + used to indicate the header of a version 2 B-link tree node. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree header. This document + describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of B-tree: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>A “testing” B-tree, this value should <em>not</em> be + used for storing records in actual HDF5 files. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>This B-tree is used for indexing indirectly accessed, + non-filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">2</td> + <td>This B-tree is used for indexing indirectly accessed, + filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">3</td> + <td>This B-tree is used for indexing directly accessed, + non-filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">4</td> + <td>This B-tree is used for indexing directly accessed, + filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">5</td> + <td>This B-tree is used for indexing the ‘name’ field for + links in indexed groups. + </td> + </tr> + <tr> + <td align="center">6</td> + <td>This B-tree is used for indexing the ‘creation order’ + field for links in indexed groups. + </td> + </tr> + <tr> + <td align="center">7</td> + <td>This B-tree is used for indexing shared object header + messages. + </td> + </tr> + <tr> + <td align="center">8</td> + <td>This B-tree is used for indexing the ‘name’ field for + indexed attributes. + </td> + </tr> + <tr> + <td align="center">9</td> + <td>This B-tree is used for indexing the ‘creation order’ + field for indexed attributes. + </td> + </tr> + </table></p> + <p>The format of records for each type is described below.</p> + </td> + </tr> + + <tr valign="top"> + <td><p>Node Size</p></td> + <td> + <p>This is the size in bytes of all B-tree nodes. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Record Size</p></td> + <td> + <p>This field is the size in bytes of the B-tree record. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Depth</p></td> + <td> + <p>This is the depth of the B-tree. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Split Percent</p></td> + <td> + <p>The percent full that a node needs to increase above before it + is split. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Merge Percent</p></td> + <td> + <p>The percent full that a node needs to be decrease below before it + is split. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Root Node Address</p></td> + <td> + <p>This is the address of the root B-tree node. A B-tree with + no records will have the <a href="#UndefinedAddress">undefined + address</a> in this field. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Number of Records in Root Node</p></td> + <td> + <p>This is the number of records in the root node. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Total Number of Records in B-tree</p></td> + <td> + <p>This is the total number of records in the entire B-tree. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the B-tree header. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree Internal Node + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Records 0, 1, 2...N-1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer 0<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Number of Records N<sub>0</sub> for Child Node 0 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node 0 <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer 1<sup>O</sup><br /><br /></td> + </tr> + <td colspan="4"><br />Number of Records N<sub>1</sub> for Child Node 1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node 1 <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4">...</td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer N<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Number of Records N<sub>n</sub> for Child Node N <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node N <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + </div> + + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTIN</code>” is + used to indicate the internal node of a B-link tree. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree internal node. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header. + </p> + </td> + </tr> + + <tr> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format + of records depends on the type of B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Child Node Pointer</p></td> + <td> + <p>This field is the address of the child node pointed to by the + internal node. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Records in Child Node</p></td> + <td> + <p>This is the number of records in the child node pointed to by + the corresponding <em>Node Pointer</em>. + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node. + </p> + <p> + The maximum number of records in a child node is computed + in the following way: + + <ul> + <li>Subtract the fixed size overhead for + the child node (for example, its signature, version, + checksum, and so on and <em>one</em> pointer triplet + of information for the child node (because there is one + more pointer triplet than records in each internal node)) + from the size of nodes for the B-tree. </li> + <li>Divide that result by the size of a record plus the + pointer triplet of information stored to reach each + child node from this node. + </ul> + + </p> + <p> + Note that leaf nodes do not encode any + child pointer triplets, so the maximum number of records in a + leaf node is just the node size minus the leaf node overhead, + divided by the record size. + </p> + <p> + Also note that the first level of internal nodes above the + leaf nodes do not encode the <em>Total Number of Records in Child + Node</em> value in the child pointer triplets (since it is the + same as the <em>Number of Records in Child Node</em>), so the + maximum number of records in these nodes is computed with the + equation above, but using (<em>Child Pointer</em>, <em>Number of + Records in Child Node</em>) pairs instead of triplets. + </p> + <p> + The number of + bytes used to encode this field is the least number of bytes + required to encode the maximum number of records in a child + node value for the child nodes below this level + in the B-tree. + </p> + <p> + For example, if the maximum number of child records is + 123, one byte will be used to encode these values in this + node; if the maximum number of child records is + 20000, two bytes will be used to encode these values in this + node; and so on. The maximum number of bytes used to + encode these values is 8 (in other words, an unsigned + 64-bit integer). + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Records in Child Node</p></td> + <td> + <p>This is the total number of records for the node pointed to by + the corresponding <em>Node Pointer</em> and all its children. + This field exists only in nodes whose depth in the B-tree node + is greater than 1 (in other words, the “twig” + internal nodes, just above leaf nodes, do not store this + field in their child node pointers). + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node and its descendants. + </p> + <p> + The maximum possible number of records able to be stored in a + child node and its descendants is computed iteratively, in the + following way: The maximum number of records in a leaf node + is computed, then that value is used to compute the maximum + possible number of records in the first level of internal nodes + above the leaf nodes. Multiplying these two values together + determines the maximum possible number of records in child node + pointers for the level of nodes two levels above leaf nodes. + This process is continued up to any level in the B-tree. + </p> + <p> + The number of bytes used to encode this value is computed in + the same way as for the <em>Number of Records in Child Node</em> + field. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree Leaf Node + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Record 0, 1, 2...N-1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTLF</code>“ is + used to indicate the leaf node of a version 2 B-link tree. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree leaf node. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header. + </p> + </td> + </tr> + + <tr> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format + of records depends on the type of B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <p>The record layout for each stored (in other words, non-testing) + B-tree type is as follows:</p> + + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 1 Record Layout - Indirectly Accessed, Non-Filtered, + ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 2 Record Layout - Indirectly Accessed, Filtered, + ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask</td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped for + this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that + filter is skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 3 Record Layout - Directly Accessed, Non-Filtered, + ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 4 Record Layout - Directly Accessed, Filtered, + ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask</td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped for + this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that + filter is skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 5 Record Layout - Link Name for Indexed Group + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Hash of Name</td> + </tr> + <tr> + <td colspan="4">ID <em>(bytes 1-4)</em></td> + </tr> + + <tr> + <td colspan="3">ID <em>(bytes 5-7)</em></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the link. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the link’s name. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 6 Record Layout - Creation Order for Indexed Group + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Creation Order <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">ID <em>(bytes 1-4)</em></td> + </tr> + <tr> + <td colspan="3">ID <em>(bytes 5-7)</em></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the link. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 7 Record Layout - Shared Object Header Messages (Sub-Type 0 - Message in Heap) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Hash</td> + </tr> + <tr> + <td colspan="4">Reference Count</td> + </tr> + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is stored: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>The number of objects which reference this message.</p> + </td> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + shared message in the shared message index’s fractal heap.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 7 Record Layout - Shared Object Header Messages (Sub-Type 1 - Message in Object Header) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Hash</td> + </tr> + <tr> + <td>Reserved (zero)</td> + <td>Message Type</td> + <td colspan="2">Object Header Index</td> + </tr> + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is stored: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Message Type</p></td> + <td> + <p>The object header message type of the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Index</p></td> + <td> + <p>This field indicates that the shared message is the n<sup>th</sup> message + of its type in the specified object header.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>The address of the object header containing the shared message.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 8 Record Layout - Attribute Name for Indexed Attributes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Creation Order</td> + </tr> + <tr> + <td colspan="4">Hash of Name</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + attribute in the object’s attribute fractal heap.</p> + </td> + </tr> + + <tr> + <td><p>Message Flags</p></td> + <td><p>The object header message flags for the attribute message.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute. + </p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the attribute. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the attribute’s name. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Version 2 B-tree, Type 9 Record Layout- Creation Order for Indexed Attributes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Creation Order</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + attribute in the object’s attribute fractal heap.</p> + </td> + </tr> + + <tr> + <td><p>Message Flags</p></td> + <td> + <p>The object header message flags for the attribute message.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute. + </p> + </td> + </tr> + + </table> + </div> + + +<br /> +<h3><a name="SymbolTable"> +III.B. Disk Format: Level 1B - Group Symbol Table Nodes</a></h3> + + <p>A group is an object internal to the file that allows + arbitrary nesting of objects within the file (including other groups). + A group maps a set of link names in the group to a set of relative + file addresses of objects in the file. Certain metadata for an object to + which the group points can be cached in the group’s symbol table entry in + addition to being in the object’s header.</p> + + <p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each + component as a link in a group. The link for a + non-ultimate component points to the group containing + the next component. The link for the last + component points to the object being named.</p> + + <p>One implementation of a group is a collection of symbol table nodes + indexed by a B-link tree. Each symbol table node contains entries + for one or more links. If an attempt is made to add a link to an already + full symbol table node containing 2<em>K</em> entries, then the node is + split and one node contains <em>K</em> symbols and the other contains + <em>K</em>+1 symbols.</p> + + <div align="center"> + <table class="format"> + <caption> + Symbol Table Node (A Leaf of a B-link tree) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version Number</td> + <td>Reserved (zero)</td> + <td colspan="2">Number of Symbols</td> + </tr> + + <tr> + <td colspan="4"><br /><br />Group Entries<br /><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SNOD</code>” is + used to indicate the + beginning of a symbol table node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version Number</p></td> + <td> + <p>The version number for the symbol table node. This + document describes version 1. (There is no version ‘0’ + of the symbol table node) + </p> + </td> + </tr> + + <tr> + <td><p>Number of Entries</p></td> + <td> + <p>Although all symbol table nodes have the same length, + most contain fewer than the maximum possible number of + link entries. This field indicates how many entries + contain valid data. The valid entries are packed at the + beginning of the symbol table node while the remaining + entries contain undefined values. + </p> + </td> + </tr> + + <tr> + <td><p>Symbol Table Entries</p></td> + <td> + <p>Each link has an entry in the symbol table node. + The format of the entry is described below. + There are 2<em>K</em> entries in each group node, where + <em>K</em> is the “Group Leaf Node K” value from the + <a href="#Superblock">superblock</a>. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h3><a name="SymbolTableEntry"> +III.C. Disk Format: Level 1C - Symbol Table Entry </a></h3> + + <p>Each symbol table entry in a symbol table node is designed + to allow for very fast browsing of stored objects. + Toward that design goal, the symbol table entries + include space for caching certain constant metadata from the + object header.</p> + + <div align="center"> + <table class="format"> + <caption> + Symbol Table Entry + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Link Name Offset<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Cache Type</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br /><br />Scratch-pad Space (16 bytes)<br /><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Link Name Offset</p></td> + <td> + <p>This is the byte offset into the group’s local + heap for the name of the link. The name is null + terminated. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>Every object has an object header which serves as a + permanent location for the object’s metadata. In addition + to appearing in the object header, some of the object’s metadata + can be cached in the scratch-pad space. + </p> + </td> + </tr> + + <tr> + <td><p>Cache Type</p></td> + <td> + <p>The cache type is determined from the object header. + It also determines the format for the scratch-pad space: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>No data is cached by the group entry. This + is guaranteed to be the case when an object header + has a link count greater than one. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Group object header metadata is cached in the + scratch-pad space. This implies that the symbol table + entry refers to another group. + </td> + </tr> + <tr> + <td align="center">2</td> + <td>The entry is a symbolic link. The first four bytes + of the scratch-pad space are the offset into the local + heap for the link value. The object header address + will be undefined. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td> + <p>These four bytes are present so that the scratch-pad + space is aligned on an eight-byte boundary. They are + always set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Scratch-pad Space</p></td> + <td> + <p>This space is used for different purposes, depending + on the value of the Cache Type field. Any metadata + about an object represented in the scratch-pad + space is duplicated in the object header for that + object. + </p> + <p> + Furthermore, no data is cached in the group + entry scratch-pad space if the object header for + the object has a link count greater than one. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h4>Format of the Scratch-pad Space</h4> + + <p>The symbol table entry scratch-pad space is formatted + according to the value in the Cache Type field.</p> + + <p>If the Cache Type field contains the value zero + <code>(0)</code> then no information is + stored in the scratch-pad space.</p> + + <p>If the Cache Type field contains the value one + <code>(1)</code>, then the scratch-pad space + contains cached metadata for another object header + in the following format:</p> + + <div align="center"> + <table class="format"> + <caption> + Object Header Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address of B-tree<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Name Heap<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address of B-tree</p></td> + <td> + <p>This is the file address for the root of the + group’s B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Name Heap</p></td> + <td> + <p>This is the file address for the group’s local + heap, in which are stored the group’s symbol names. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <p>If the Cache Type field contains the value two + <code>(2)</code>, then the scratch-pad space + contains cached metadata for a symbolic link + in the following format:</p> + + <div align="center"> + <table class="format"> + <caption> + Symbolic Link Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Offset to Link Value</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Offset to Link Value</p></td> + <td> + <p>The value of a symbolic link (that is, the name of the + thing to which it points) is stored in the local heap. + This field is the 4-byte offset into the local heap for + the start of the link value, which is null terminated. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h3><a name="LocalHeap"> +III.D. Disk Format: Level 1D - Local Heaps</a></h3> + + <p>A local heap is a collection of small pieces of data that are particular + to a single object in the HDF5 file. Objects can be + inserted and removed from the heap at any time. + The address of a heap does not change once the heap is created. + For example, a group stores addresses of objects in symbol table nodes + with the names of links stored in the group’s local heap. + </p> + + <div align="center"> + <table class="format"> + <caption> + Local Heap + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Data Segment Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset to Head of Free-list<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Data Segment<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>HEAP</code>” + is used to indicate the + beginning of a heap. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>Each local heap has its own version number so that new + heaps can be added to old files. This document + describes version zero (0) of the local heap. + </p> + </td> + </tr> + + <tr> + <td><p>Data Segment Size</p></td> + <td> + <p>The total amount of disk memory allocated for the heap + data. This may be larger than the amount of space + required by the objects stored in the heap. The extra + unused space in the heap holds a linked list of free blocks. + </p> + </td> + </tr> + + <tr> + <td><p>Offset to Head of Free-list</p></td> + <td> + <p>This is the offset within the heap data segment of the + first free block (or the + <a href="#UndefinedAddress">undefined address</a> if there is no + free block). The free block contains “Size of Lengths” bytes that + are the offset of the next free block (or the + value ‘1’ if this is the + last free block) followed by “Size of Lengths” bytes that store + the size of this free block. The size of the free block includes + the space used to store the offset of the next free block and + the size of the current block, making the minimum size of a free + block 2 * “Size of Lengths”. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Data Segment</p></td> + <td> + <p>The data segment originally starts immediately after + the heap header, but if the data segment must grow as a + result of adding more objects, then the data segment may + be relocated, in its entirety, to another part of the + file. + </p> + </td> + </tr> + </table> + </div> + + <p>Objects within a local heap should be aligned on an 8-byte boundary.</p> + +<br /> +<h3><a name="GlobalHeap"> +III.E. Disk Format: Level 1E - Global Heap</a></h3> + + <p>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The + global heap was designed to satisfy these goals:</p> + + <ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap + objects will typically be shared among several datasets, it is + probable that the object will be accessed repeatedly.</li> + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of + object references will have a global heap object for each + reference. Reading the entire set of object references + should result in a few large I/O requests instead of one small + I/O request for each reference.</li> + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed + for other uses.</li> + </ol> + + + <p>The implementation of the heap makes use of the memory management + already available at the file level and combines that with a new + object called a <em>collection</em> to achieve goal B. The global heap + is the set of all collections. Each global heap object belongs to + exactly one collection and each collection contains one or more global + heap objects. For the purposes of disk I/O and caching, a collection is + treated as an atomic object, addressing goal A. + </p> + + <p>When a global heap object is deleted from a collection (which occurs + when its reference count falls to zero), objects located after the + deleted object in the collection are packed down toward the beginning + of the collection and the collection’s global heap object 0 is created + (if possible) or its size is increased to account for the recently + freed space. There are no gaps between objects in each collection, + with the possible exception of the final space in the collection, if + it is not large enough to hold the header for the collection’s global + heap object 0. These features address goal C. + </p> + + <p>The HDF5 Library creates global heap collections as needed, so there may + be multiple collections throughout the file. The set of all of them is + abstractly called the “global heap”, although they do not actually link + to each other, and there is no global place in the file where you can + discover all of the collections. The collections are found simply by + finding a reference to one through another object in the file. For + example, data of variable-length datatype elements is stored in the + global heap and is accessed via a global heap ID. The format for + global heap IDs is described at the end of this section. + </p> + + <div align="center"> + <table class="format"> + <caption> + A Global Heap Collection + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Collection Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object <em>N</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 0 (free space)<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>GCOL</code>” + is used to indicate the + beginning of a collection. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>Each collection has its own version number so that new + collections can be added to old files. This document + describes version one (1) of the collections (there is no + version zero (0)). + </p> + </td> + </tr> + + <tr> + <td><p>Collection Size</p></td> + <td> + <p>This is the size in bytes of the entire collection + including this field. The default (and minimum) + collection size is 4096 bytes which is a typical file + system block size. This allows for 127 16-byte heap + objects plus their overhead (the collection header of 16 bytes + and the 16 bytes of information about each heap object). + </p> + </td> + </tr> + + <tr> + <td><p>Global Heap Object 1 through <em>N</em></p></td> + <td> + <p>The objects are stored in any order with no + intervening unused space. + </p> + </td> + </tr> + + <tr> + <td><p>Global Heap Object 0</p></td> + <td> + <p>Global Heap Object 0 (zero), when present, represents the free + space in the collection. Free space always appears at the end of + the collection. If the free space is too small to store the header + for Object 0 (described below) then the header is implied and the + collection contains no free space. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Global Heap Object + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="2">Heap Object Index</td> + <td colspan="2">Reference Count</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Object Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Object Data<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap Object Index</p></td> + <td> + <p>Each object has a unique identification number within a + collection. The identification numbers are chosen so that + new objects have the smallest value possible with the + exception that the identifier <code>0</code> always refers to the + object which represents all free space within the + collection. + </p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>All heap objects have a reference count field. An + object which is referenced from some other part of the + file will have a positive reference count. The reference + count for Object 0 is always zero. + </p> + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td> + <p>Zero padding to align next field on an 8-byte boundary. + </p> + </td> + </tr> + + <tr> + <td><p>Object Size</p></td> + <td> + <p>This is the size of the object data stored for the object. + The actual storage space allocated for the object data is rounded + up to a multiple of eight. + </p> + </td> + </tr> + + <tr> + <td><p>Object Data</p></td> + <td> + <p>The object data is treated as a one-dimensional array + of bytes to be interpreted by the caller. + </p> + </td> + </tr> + </table> + + </div> + + <br /> + <p> + The format for the ID used to locate an object in the global heap is + described here:</p> + + <div align="center"> + <table class="format"> + <caption> + Global Heap ID + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Collection Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Object Index</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Collection Address</p></td> + <td> + <p>This field is the address of the global heap collection + where the data object is stored. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This field is the index of the data object within the + global heap collection. + </p> + </td> + </tr> + + </table> + </div> + + +<br /> +<h3><a name="FractalHeap"> +III.F. Disk Format: Level 1F - Fractal Heap</a></h3> + + <p> + Each fractal heap consists of a header and zero or more direct and + indirect blocks (described below). The header contains general + information as well as + initialization parameters for the doubling table. The <em>Root + Block Address</em> in the header points to the first direct or + indirect block in the heap. + </p> + + <p> + Fractal heaps are based on a data structure called a <em>doubling + table</em>. A doubling table provides a mechanism for quickly + extending an array-like data structure that minimizes the number of + empty blocks in the heap, while retaining very fast lookup of any + element within the array. More information on fractal heaps and + doubling tables can be found in the RFC + “<a href="Supplements/FractalHeap/PrivateHeap.pdf">Private + Heaps in HDF5</a>.” + </p> + + <p> + The fractal heap implements the doubling table structure with + indirect and direct blocks. + Indirect blocks in the heap do not actually contain data for + objects in the heap, their “size” is abstract - + they represent the indexing structure for locating the + direct blocks in the doubling table. + Direct blocks + contain the actual data for objects stored in the heap. + </p> + + <p> + All indirect blocks have a constant number of block entries in each + row, called the <em>width</em> of the doubling table (stored in + the heap header). + + The number + of rows for each indirect block in the heap is determined by the + size of the block that the indirect block represents in the + doubling table (calculation of this is shown below) and is + constant, except for the “root” + indirect block, which expands and shrinks its number of rows as + needed. + </p> + + <p> + Blocks in the first <em>two</em> rows of an indirect block + are <em>Starting Block Size</em> number of bytes in size, + and the blocks in each subsequent row are twice the size of + the blocks in the previous row. In other words, blocks in + the third row are twice the <em>Starting Block Size</em>, + blocks in the fourth row are four times the + <em>Starting Block Size</em>, and so on. Entries for + blocks up to the <em>Maximum Direct Block Size</em> point to + direct blocks, and entries for blocks greater than that size + point to further indirect blocks (which have their own + entries for direct and indirect blocks). + </p> + + <p> + The number of rows of blocks, <em>nrows</em>, in an + indirect block of size <em>iblock_size</em> is given by the + following expression: + <br /> <br /> + <em>nrows</em> = (log<sub>2</sub>(<em>iblock_size</em>) - + log<sub>2</sub>(<em><Starting Block Size></em> * + <em><Width></em>)) + 1 + </p> + + <p> + The maximum number of rows of direct blocks, <em>max_dblock_rows</em>, + in any indirect block of a fractal heap is given by the + following expression: + <br /> <br /> + <em>max_dblock_rows</em> = + (log<sub>2</sub>(<em><Max. Direct Block Size></em>) - + log<sub>2</sub>(<em><Starting Block Size></em>)) + 2 + </p> + + <p> + Using the computed values for <em>nrows</em> and + <em>max_dblock_rows</em>, along with the <em>Width</em> of the + doubling table, the number of direct and indirect block entries + (<em>K</em> and <em>N</em> in the indirect block description, below) + in an indirect block can be computed: + <br /> <br /> + <em>K</em> = MIN(<em>nrows</em>, <em>max_dblock_rows</em>) * + <em>Width</em> + + <br /> <br /> + If <em>nrows</em> is less than or equal to <em>max_dblock_rows</em>, + <em>N</em> is 0. Otherwise, <em>N</em> is simply computed: + <br /> <br /> + <em>N</em> = <em>K</em> - (<em>max_dblock_rows</em> * + <em>Width</em>) + </p> + + <p> + The size indirect blocks on disk is determined by the number + of rows in the indirect block (computed above). The size of direct + blocks on disk is exactly the size of the block in the doubling + table. + </p> + + <div align="center"> + <table class="format"> + <caption> + Fractal Heap Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Heap ID Length</td> + <td colspan="2">I/O Filters’ Encoded Length</td> + </tr> + + <tr> + <td>Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Maximum Size of Managed Objects</td> + </tr> + + <tr> + <td colspan="4"><br />Next Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />v2 B-tree Address of Huge Objects<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Free Space in Managed Blocks<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Managed Block Free Space Manager<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Managed Space in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Allocated Managed Space in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset of Direct Block Allocation Iterator in Managed Space<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Managed Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Huge Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Huge Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Table Width</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Starting Block Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Direct Block Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Maximum Heap Size</td> + <td colspan="2">Starting # of Rows in Root Indirect Block</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Root Block<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Current # of Rows in Root Indirect Block</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Filtered Root Direct Block <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">I/O Filter Mask<em> (optional)</em></td> + </tr> + + <tr> + <td colspan="4">I/O Filter Information<em> (optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FRHP</code>” + is used to indicate the + beginning of a fractal heap header. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap ID Length</p></td> + <td> + <p>This is the length in bytes of heap object IDs for this heap.</p> + </td> + </tr> + + <tr> + <td><p>I/O Filters’ Encoded Length</p></td> + <td> + <p>This is the size in bytes of the encoded <em>I/O Filter Information</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is the heap status flag and is a bit field + indicating additional information about the fractal heap. + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the ID value to use for huge object has wrapped + around. If the value for the <em>Next Huge Object ID</em> + has wrapped around, each new huge object inserted into the + heap will require a search for an ID value. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the direct blocks in the heap are checksummed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Size of Managed Objects</p></td> + <td> + <p>This is the maximum size of managed objects allowed in the heap. + Objects greater than this this are ‘huge’ objects and will be + stored in the file directly, rather than in a direct block for + the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Next Huge Object ID</p></td> + <td> + <p>This is the next ID value to use for a huge object in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>v2 B-tree Address of Huge Objects</p></td> + <td> + <p>This is the address of the <a href="#V2Btrees">v2 B-tree</a> + used to track huge objects in the heap. The type of records + stored in the <em>v2 B-tree</em> will + be determined by whether the address & length of a huge object + can fit into a heap ID (if yes, it is a “directly” accessed + huge object) and whether there is a filter used on objects + in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Free Space in Managed Blocks</p></td> + <td> + <p>This is the total amount of free space in managed direct blocks + (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Address of Managed Block Free Space Manager</p></td> + <td> + <p>This is the address of the + <em><a href="#FreeSpaceManager">Free-space Manager</a></em> for + managed blocks. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Managed Space in Heap</p></td> + <td> + <p>This is the total amount of managed space in the heap (in bytes), + essentially the upper bound of the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Allocated Managed Space in Heap</p></td> + <td> + <p>This is the total amount of managed space (in bytes) actually + allocated in + the heap. This can be less than the <em>Amount of Managed Space + in Heap</em> field, if some direct blocks in the heap’s linear + address space are not allocated. + </p> + </td> + </tr> + + <tr> + <td><p>Offset of Direct Block Allocation Iterator in Managed Space</p></td> + <td> + <p>This is the linear heap offset where the next direct + block should be allocated at (in bytes). This may be less than + the <em>Amount of Managed Space in Heap</em> value because the + heap’s address space is increased by a “row” of direct blocks + at a time, rather than by single direct block increments. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Managed Objects in Heap</p></td> + <td> + <p>This is the number of managed objects in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Huge Objects in Heap</p></td> + <td> + <p>This is the total size of huge objects in the heap (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Number of Huge Objects in Heap</p></td> + <td> + <p>This is the number of huge objects in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Tiny Objects in Heap</p></td> + <td> + <p>This is the total size of tiny objects that are packed in heap + IDs (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Number of Tiny Objects in Heap</p></td> + <td> + <p>This is the number of tiny objects that are packed in heap IDs. + </p> + </td> + </tr> + + <tr> + <td><p>Table Width</p></td> + <td> + <p>This is the number of columns in the doubling table for managed + blocks. This value must be a power of two. + </p> + </td> + </tr> + + <tr> + <td><p>Starting Block Size</p></td> + <td> + <p>This is the starting block size to use in the doubling table for + managed blocks (in bytes). This value must be a power of two. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Direct Block Size</p></td> + <td> + <p>This is the maximum size allowed for a managed direct block. + Objects inserted into the heap that are larger than this value + (less the # of bytes of direct block prefix/suffix) + are stored as ‘huge’ objects. This value must be a power of + two. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Heap Size</p></td> + <td> + <p>This is the maximum size of the heap’s linear address space for + managed objects (in bytes). The value stored is the log2 of + the actual value, that is: the # of bits of the address space. + ‘Huge’ and ‘tiny’ objects are not counted in this value, since + they do not store objects in the linear address space of the + heap. + </p> + </td> + </tr> + + <tr> + <td><p>Starting # of Rows in Root Indirect Block</p></td> + <td> + <p>This is the starting number of rows for the root indirect block. + A value of 0 indicates that the root indirect block will have + the maximum number of rows needed to address the heap’s <em>Maximum + Heap Size</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Root Block</p></td> + <td> + <p>This is the address of the root block for the heap. It can + be the <a href="#UndefinedAddress">undefined address</a> if + there is no data in the heap. It either points to a direct + block (if the <em>Current # of Rows in the Root Indirect Block</em> + value is 0), or an indirect block. + </p> + </td> + </tr> + + <tr> + <td><p>Current # of Rows in Root Indirect Block</p></td> + <td> + <p>This is the current number of rows in the root indirect block. + A value of 0 indicates that <em>Address of Root Block</em> + points to direct block instead of indirect block. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Filtered Root Direct Block</p></td> + <td> + <p>This is the size of the root direct block, if filters are + applied to heap objects (in bytes). This field is only + stored in the header if the <em>I/O Filters’ Encoded Length</em> + is greater than 0. + </p> + </td> + </tr> + + <tr> + <td><p>I/O Filter Mask</p></td> + <td> + <p>This is the filter mask for the root direct block, if filters + are applied to heap objects. This mask has the same format as + that used for the filter mask in chunked raw data records in a + <a href="#V1Btrees">v1 B-tree</a>. + This field is only + stored in the header if the <em>I/O Filters’ Encoded Length</em> + is greater than 0. + </p> + </td> + </tr> + + <tr> + <td><p>I/O Filter Information</p></td> + <td> + <p>This is the I/O filter information encoding direct blocks and + huge objects, if filters are applied to heap objects. This + field is encoded as a <a href="#FilterMessage">Filter Pipeline</a> + message. + The size of this field is determined by <em>I/O Filters’ + Encoded Length</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the header.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap Direct Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Object Data <em>(variable size)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FHDB</code>” + is used to indicate the + beginning of a fractal heap direct block. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode + this field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is + principally used for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the direct block.</p> + <p>This field is only present if bit 1 of <em>Flags</em> in the + heap’s header is set.</p> + </td> + </tr> + + <tr> + <td><p>Object Data</p></td> + <td> + <p>This section of the direct block stores the actual data for + objects in the heap. The size of this section is determined by + the direct block’s size minus the size of the other fields + stored in the direct block (for example, the <em>Signature</em>, + <em>Version</em>, and others including the <em>Checksum</em> if it is + present). + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap Indirect Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #0 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #0 <em>(optional)</em> <sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #0 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #1 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #1 <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #1 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #K-1 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #K-1 <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #K-1 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #0 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #1 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #N-1 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FHIB</code>” is used to + indicate the beginning of a fractal heap indirect block. This + gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode + this field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is + principally used for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Child Direct Block #K Address</p></td> + <td> + <p>This field is the address of the child direct block. + The size of the [uncompressed] direct block can be computed by + its offset in the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Filtered Direct Block #K</p></td> + <td> + <p>This is the size of the child direct block after passing through + the I/O filters defined for this heap (in bytes). If no I/O + filters are present for this heap, this field is not present. + </p> + </td> + </tr> + <tr> + <td><p>Filter Mask for Direct Block #K</p></td> + <td> + <p>This is the I/O filter mask for the filtered direct block. + This mask has the same format as that used for the filter mask + in chunked raw data records in a <a href="#V1Btrees">v1 B-tree</a>. + If no I/O filters are present for this heap, this field is not + present. + </p> + </td> + </tr> + + <tr> + <td><p>Child Indirect Block #N Address</p></td> + <td> + <p>This field is the address of the child indirect block. + The size of the indirect block can be computed by + its offset in the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the indirect block.</p> + </td> + </tr> + + </table> + + </div> + + <br /> + <p>An object in the fractal heap is identified by means of a fractal heap ID, + which encodes information to locate the object in the heap. + Currently, the fractal heap stores an object in one of three ways, + depending on the object’s size:</p> + + <div align="center"> + <table class="list80"> + <tr> + <th width="20%">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center">Tiny</td> + <td> + <p>When an object is small enough to be encoded in the heap ID, the + object’s data is embedded in the fractal heap ID itself. There are + 2 sub-types for this type of object: normal and extended. The + sub-type for tiny heap IDs depends on whether the heap ID is large + enough to store objects greater than 16 bytes or not. If the + heap ID length is 18 bytes or smaller, the ‘normal’ tiny heap ID + form is used. If the heap ID length is greater than 18 bytes in + length, the “extented” form is used. See format description below + for both sub-types. + </p> + </td> + </tr> + + <tr> + <td align="center">Huge</td> + <td> + <p>When the size of an object is larger than <em>Maximum Size of + Managed Objects</em> in the <em>Fractal Heap Header</em>, the + object’s data is stored on its own in the file and the object + is tracked/indexed via a version 2 B-tree. All huge objects + for a particular fractal heap use the same v2 B-tree. All huge + objects for a particular fractal heap use the same format for + their huge object IDs. + </p> + + <p>Depending on whether the IDs for a heap are large enough to hold + the object’s retrieval information and whether I/O pipeline filters + are applied to the heap’s objects, 4 sub-types are derived for + huge object IDs for this heap:</p> + + <div align="center"> + <table class="list"> + <tr> + <th align="left" width="35%">Sub-type</th> + <th align="left">Description</th> + </tr> + + <tr> + <td align="left">Directly accessed, non-filtered</td> + <td> + <p>The object’s address and length are embedded in the + fractal heap ID itself and the object is directly accessed + from them. This allows the object to be accessed without + resorting to the B-tree. + </p> + </td> + </tr> + + <tr> + <td align="left">Directly accessed, filtered</td> + <td> + <p>The filtered object’s address, length, filter mask and + de-filtered size are embedded in the fractal heap ID itself + and the object is accessed directly with them. This allows + the object to be accessed without resorting to the B-tree. + </p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, non-filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the address and length from + the version 2 B-tree for huge objects. Then, the address + and length are used to access the object. + </p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the filtered object’s + address, length, filter mask and de-filtered size from the + version 2 B-tree for huge objects. Then, this information + is used to access the object. + </p> + </td> + </tr> + </table> + </div> + + </td> + </tr> + + <tr> + <td align="center">Managed</td> + <td> + <p>When the size of an object does not meet the above two + conditions, the object is stored and managed via the direct and + indirect blocks based on the doubling table. + </p> + </td> + </tr> + </table> + </div> + + + <p>The specific format for each type of heap ID is described below: + </p> + + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Tiny Objects (sub-type 1 - ‘Normal’) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version, Type & Length</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version, Type & Length</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>The length of the tiny object. The value stored + is one less than the actual length (since zero-length + objects are not allowed to be stored in the heap). + For example, an object of actual length 1 has an + encoded length of 0, an object of actual length 2 + has an encoded length of 1, and so on. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td> + <p>This is the data for the object. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Tiny Objects (sub-type 2 - ‘Extended’) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version, Type & Length</td> + <td>Extended Length</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Data <em>(variable size)</em></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version, Type & Length</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>These 4 bits, together with the next byte, form an + unsigned 12-bit integer for holding the length of the + object. These 4-bits are bits 8-11 of the 12-bit integer. + See description for the <em>Extended Length</em> field below. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Extended Length</p></td> + <td> + <p>This byte, together with the 4 bits in the previous byte, + forms an unsigned 12-bit integer for holding the length of + the tiny object. These 8 bits are bits 0-7 of the 12-bit + integer formed. The value stored is one less than the actual + length (since zero-length objects are not allowed to be + stored in the heap). For example, an object of actual length + 1 has an encoded length of 0, an object of actual length + 2 has an encoded length of 1, and so on. + </p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td> + <p>This is the data for the object. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 1 & 2): indirectly accessed, non-filtered/filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />v2 B-tree Key<sup>L</sup><em> (variable size)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>v2 B-tree Key</p></td> + <td><p>This field is the B-tree key for retrieving the information + from the version 2 B-tree for huge objects needed to access the + object. See the description of <a href="#V2Btrees">v2 B-tree</a> + records sub-type 1 & 2 for a description of the fields. New key + values are derived from <em>Next Huge Object ID</em> in the + <em>Fractal Heap Header</em>.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 3): directly accessed, non-filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This field is the address of the object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the object in the file.</p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 4): directly accessed, filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filter Mask</td> + </tr> + + <tr> + <td colspan="4"><br />De-filtered Size <sup>L</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This field is the address of the filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td><p>This field is the I/O pipeline filter mask for the + filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Filtered Size</p></td> + <td><p>This field is the size of the de-filtered object in the file.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Managed Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Length <em>(variable size)</em></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version & Type</p></td> + <td><p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Managed objects have a value of <code>0</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Offset</p></td> + <td><p>This field is the offset of the object in the heap. + This field’s size is the minimum number of bytes + necessary to encode the <em>Maximum Heap Size</em> value + (from the <em>Fractal Heap Header</em>). For example, if the + value of the <em>Maximum Heap Size</em> is less than 256 bytes, + this field is 1 byte in length, a <em>Maximum Heap Size</em> + of 256-65535 bytes uses a 2 byte length, and so on.</p></td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the object in the heap. It + is determined by taking the minimum value of <em>Maximum + Direct Block Size</em> and <em>Maximum Size of Managed + Objects</em> in the <em>Fractal Heap Header</em>. Again, + the minimum number of bytes needed to encode that value is + used for the size of this field.</p></td> + </tr> + </table> + </div> + +<br /> +<h3><a name="FreeSpaceManager"> +III.G. Disk Format: Level 1G - Free-space Manager</a></h3> + + <p> + Free-space managers are used to describe space within a heap or + the entire HDF5 file that is not currently used for that heap or + file. + </p> + + <p> + The <em>free-space manager header</em> contains metadata information + about the space being tracked, along with the address of the list + of <em>free space sections</em> which actually describes the free + space. The header records information about free-space sections being + tracked, creation parameters for handling free-space sections of a + client, and section information used to locate the collection of + free-space sections. + </p> + + <p> + The <em>free-space section list</em> stores a collection of + free-space sections that is specific to each <em>client</em> of the + free-space manager. + + For example, the fractal heap is a client of the free space manager + and uses it to track unused space within the heap. There are 4 + types of section records for the fractal heap, each of which has + its own format, listed below. + </p> + + <div align="center"> + <table class="format"> + <caption> + Free-space Manager Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Total Space Tracked<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Total Number of Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Serialized Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Un-Serialized Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Number of Section Classes</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Shrink Percent</td> + <td colspan="2">Expand Percent</td> + </tr> + + <tr> + <td colspan="2">Size of Address Space</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Section Size <sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Serialized Section List<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Serialized Section List Used<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Allocated Size of Serialized Section List<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FSHD</code>” is used to + indicate the beginning of the Free-space Manager Header. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Manager Header + and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>This is the client ID for identifying the user of this + free-space manager: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Fractal heap + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>File + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Total Space Tracked</p></td> + <td> + <p>This is the total amount of free space being tracked, in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Sections</p></td> + <td> + <p>This is the total number of free-space sections being tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Serialized Sections</p></td> + <td> + <p>This is the number of serialized free-space sections being + tracked. + </p> + </td> + </tr> + <tr> + <td><p>Number of Un-Serialized Sections</p></td> + <td> + <p>This is the number of un-serialized free-space sections being + managed. Un-serialized sections are created by the free-space + client when the list of sections is read in. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Section Classes</p></td> + <td> + <p>This is the number of section classes handled by this free space + manager for the free-space client. + </p> + </td> + </tr> + + <tr> + <td><p>Shrink Percent</p></td> + <td> + <p>This is the percent of current size to shrink the allocated + serialized free-space section list. + </p> + </td> + </tr> + + <tr> + <td><p>Expand Percent</p></td> + <td> + <p>This is the percent of current size to expand the allocated + serialized free-space section list. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Address Space</p></td> + <td> + <p>This is the size of the address space that free-space sections + are within. This is stored as the log<sub>2</sub> of the + actual value (in other words, the number of bits required + to store values within that address space). + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Section Size</p></td> + <td> + <p>This is the maximum size of a section to be tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Serialized Section List</p></td> + <td> + <p>This is the address where the serialized free-space section + list is stored. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Serialized Section List Used</p></td> + <td> + <p>This is the size of the serialized free-space section + list used (in bytes). This value must be less than + or equal to the <em>allocated size of serialized section + list</em>, below. + </p> + </td> + </tr> + + <tr> + <td><p>Allocated Size of Serialized Section List</p></td> + <td> + <p>This is the size of serialized free-space section list + actually allocated (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the free-space manager header.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <p>The free-space sections being managed are stored in a + <em>free-space section list</em>, described below. The sections + in the free-space section list are stored in the following way: + a count of the number of sections describing a particular size of + free space and the size of the free-space described (in bytes), + followed by a list of section description records; then another + section count and size, followed by the list of section + descriptions for that size; and so on.</p> + + + <div align="center"> + <table class="format"> + <caption> + Free-space Section List + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Free-space Manager Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #0 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #0 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #0 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #0 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> + + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #N-1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #N-1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #N-1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #N-1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Data <em>(variable size)</td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FSSE</code>” is used to + indicate the beginning of the Free-space Section Information. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Section List + and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Free-space Manager Header Address</p></td> + <td> + <p>This is the address of the <em>Free-space Manager Header</em>. + This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Section Records for Set #N</p></td> + <td> + <p>This is the number of free-space section records for set #N. + The length of this field is the minimum number of bytes needed + to store the <em>number of serialized sections</em> (from the + <em>free-space manager header</em>). + </p> + + <p> + The number of sets of free-space section records is + determined by the <em>size of serialized section list</em> in + the <em>free-space manager header</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Section Size for Record Set #N</p></td> + <td> + <p>This is the size (in bytes) of the free-space section described + for <em>all</em> the section records in set #N. + </p> + + <p> + The length of this field is the minimum number of bytes needed + to store the <em>maximum section size</em> (from the + <em>free-space manager header</em>). + </p> + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Offset</p></td> + <td> + <p>This is the offset (in bytes) of the free-space section within + the client for the free-space manager. + </p> + + <p> + The length of this field is the minimum number of bytes needed + to store the <em>size of address space</em> (from the + <em>free-space manager header</em>). + </p> + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Type</p></td> + <td> + <p>This is the type of the section record, used to decode the + <em>record set #N section #K data</em> information. The defined + record type for <em>file</em> client is: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>File’s section (a range of actual bytes in file) + </td> + </tr> + <tr> + <td align="center"><code>1+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + <p>The defined record types for a <em>fractal heap</em> client are: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Fractal heap “single” section + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Fractal heap “first row” section + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Fractal heap “normal row” section + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Fractal heap “indirect” section + </td> + </tr> + + <tr> + <td align="center"><code>4+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Data</p></td> + <td> + <p>This is the section-type specific information for each record + in the record set, described below. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the <em>Free-space Section List</em>. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <p> + The section-type specific data for each free-space section record is + described below: + </p> + + <div align="center"> + <table class="format"> + <caption> + File’s Section Data Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap “Single” Section Data Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap “First Row” Section Data Record + </caption> + + <tr> + <td colspan="4"><em>Same format as “indirect” section data</em></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap “Normal Row” Section Data Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Fractal Heap “Indirect” Section Data Record + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Fractal Heap Indirect Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="2">Block Start Row</td> + <td colspan="2">Block Start Column</td> + </tr> + + <tr> + <td colspan="2">Number of Blocks</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Fractal Heap Block Offset</p></td> + <td> + <p>The offset of the indirect block in the fractal heap’s address + space containing the empty blocks. + </p> + <p> + The number of bytes used to encode this field is the minimum + number of bytes needed to encode values for the <em>Maximum + Heap Size</em> (in the fractal heap’s header). + </p> + </td> + </tr> + + <tr> + <td><p>Block Start Row</p></td> + <td> + <p>This is the row that the empty blocks start in. + </p> + </td> + </tr> + + <tr> + <td><p>Block Start Column</p></td> + <td> + <p>This is the column that the empty blocks start in. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Blocks</p></td> + <td> + <p>This is the number of empty blocks covered by the section. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h3><a name="SOHMTable"> +III.H. Disk Format: Level 1H - Shared Object Header Message Table</a></h3> + + <p> + The <em>shared object header message table</em> is used to locate + object + header messages that are shared between two or more object headers + in the file. Shared object header messages are stored and indexed + in the file in one of two ways: indexed sequentially in a + <em>shared header message list</em> or indexed with a v2 B-tree. + The shared messages themselves are either stored in a fractal + heap (when two or more objects share the message), or remain in an + object’s header (when only one object uses the message currently, + but the message can be shared in the future). + </p> + + <p> + The <em>shared object header message table</em> + contains a list of shared message index headers. Each index header + records information about the version of the index format, the index + storage type, flags for the message types indexed, the number of + messages in the index, the address where the index resides, + and the fractal heap address if shared messages are stored there. + </p> + + <p> + Each index can be either a list or a v2 B-tree and may transition + between those two forms as the number of messages in the index + varies. Each shared message record contains information used to + locate the shared message from either a fractal heap or an object + header. The types of messages that can be shared are: <em>Dataspace, + Datatype, Fill Value, Filter Pipeline and Attribute</em>. + </p> + + <p> + The <em>shared object header message table</em> is pointed to + from a <a href="#SOHMTableMessage">shared message table</a> message + in the superblock extension for a file. This message stores the + version of the table format, along with the number of index headers + in the table. + </p> + + <div align="center"> + <table class="format"> + <caption> + Shared Object Header Message Table + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version for index #0</td> + <td>Index Type for index #0</td> + <td colspan="2">Message Type Flags for index #0</td> + </tr> + + <tr> + <td colspan="4">Minimum Message Size for index #0</td> + </tr> + + <tr> + <td colspan="2">List Cutoff for index #0</td> + <td colspan="2">v2 B-tree Cutoff for index #0</td> + </tr> + + <tr> + <td colspan="2">Number of Messages for index #0</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #0<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #0<br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td>Version for index #N-1</td> + <td>Index Type for index #N-1</td> + <td colspan="2">Message Type Flags for index #N-1</td> + </tr> + + <tr> + <td colspan="4">Minimum Message Size for index #N-1</td> + </tr> + + <tr> + <td colspan="2">List Cutoff for index #N-1</td> + <td colspan="2">v2 B-tree Cutoff for index #N-1</td> + </tr> + + <tr> + <td colspan="2">Number of Messages for index #N-1</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #N-1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #N-1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SMTB</code>” is used to + indicate the beginning of the Shared Object Header Message table. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version for index #N</p></td> + <td> + <p>This is the version number for the list of shared object header message + indexes and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Index Type for index #N</p></td> + <td> + <p>The type of index can be an unsorted list or a v2 B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Message Type Flags for index #N</p></td> + <td> + <p>This field indicates the type of messages tracked in the index, + as follows: + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the index tracks <em>Dataspace Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the message tracks <em>Datatype Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, the message tracks <em>Fill Value Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, the message tracks <em>Filter Pipeline Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, the message tracks <em>Attribute Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>5-15</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + + <p> + An index can track more than one type of message, but each type + of message can only by in one index. + </p> + </td> + </tr> + + <tr> + <td><p>Minimum Message Size for index #N</p></td> + <td> + <p>This is the message size sharing threshold for the index. + If the encoded size of the message is less than this value, the + message is not shared. + </p> + </td> + </tr> + + <tr> + <td><p>List Cutoff for index #N</p></td> + <td> + <p>This is the cutoff value for the indexing of messages to + switch from a list to a v2 B-tree. If the number of messages + is greater than this value, the index should be a v2 B-tree. + </p> + </td> + </tr> + <tr> + <td><p>v2 B-tree Cutoff for index #N</p></td> + <td> + <p>This is is the cutoff value for the indexing of messages to + switch from a v2 B-tree back to a list. If the number of + messages is less than this value, the index should be a list. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Messages for index #N</p></td> + <td> + <p>The number of shared messages being tracked for the index. + </p> + </td> + </tr> + + <tr> + <td><p>Index Address for index #N</p></td> + <td> + <p>This field is the address of the list or v2 B-tree where the + index nodes reside. + </p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address for index #N</p></td> + <td> + <p>This field is the address of the fractal heap if shared messages + are stored there. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the table.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <p> + Shared messages are indexed either with a <em>shared message record + list</em>, described below, or using a v2 B-tree (using record type 7). + The number of records in the <em>shared message record list</em> is + determined in the index’s entry in the <em>shared object header message + table</em>. + </p> + + <div align="center"> + <table class="format"> + <caption> + Shared Message Record List + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #0</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #1</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #N-1</td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SMLI</code>” is used to + indicate the beginning of a list of index nodes. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Shared Message Record #N</p></td> + <td> + <p>The record for locating the shared message, either in the + fractal heap for the index, or an object header (see format for + <em>index nodes</em> below). + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the list. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <p> + The record for each shared message in an index is stored in one of the + following forms: + </p> + + <div align="center"> + <table class="format"> + <caption> + Shared Message Record, for messages stored in a fractal heap + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Hash Value</td> + </tr> + + <tr> + <td colspan="4">Reference Count</td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap ID<br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 0 indicating that the message is stored in + the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message. + </p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>This is the number of times the message is used in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap ID</p></td> + <td> + <p>This is an 8-byte fractal heap ID for the message as stored in + the fractal heap for the index. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Shared Message Record, for messages stored in an object header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Hash Value</td> + </tr> + + <tr> + <td>Reserved</td> + <td>Message Type</td> + <td colspan="2">Creation Index</td> + </tr> + + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 1 indicating that the message is stored in + an object header. + </p> + </td> + </tr> + + <tr> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message. + </p> + </td> + </tr> + + <tr> + <td><p>Message Type</p></td> + <td> + <p>This is the message type in the object header. + </p> + </td> + </tr> + + <tr> + <td><p>Creation Index</p></td> + <td> + <p>This is the creation index of the message within the object + header. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>This is the address of the object header where the message is + located. + </p> + </td> + </tr> + </table> + </div> + + + +<br /> +<br /> +<hr /> +<h2><a name="DataObject"> +IV. Disk Format: Level 2 - Data Objects </a></h2> + + <p>Data objects contain the “real” user-visible information in the file. + These objects compose the scientific data and other information which + are generally thought of as “data” by the end-user. All the + other information in the file is provided as a framework for + storing and accessing these data objects. + </p> + + <p>A data object is composed of header and data + information. The header information contains the information + needed to interpret the data information for the object as + well as additional “metadata” or pointers to additional + “metadata” used to describe or annotate each object. + </p> + +<br /> +<h3><a name="ObjectHeader"> +IV.A. Disk Format: Level 2A - Data Object Headers</a></h3> + + <p>The header information of an object is designed to encompass + all of the information about an object, except for the data itself. + This information includes the dataspace, the datatype, information + about how the data is stored on disk (in external files, compressed, + broken up in blocks, and so on), as well as other information used + by the library to speed up access to the data objects or maintain + a file’s integrity. Information stored by user applications + as attributes is also stored in the object’s header. The header + of each object is not necessarily located immediately prior to the + object’s data in the file and in fact may be located in any + position in the file. The order of the messages in an object header + is not significant.</p> + + <p>Object headers are composed of a prefix and a set of messages. The + prefix contains the information needed to interpret the messages and + a small amount of metadata about the object, and the messages contain + the majority of the metadata about the object. + </p> + +<br /> +<h3><a name="ObjectHeaderPrefix"> +IV.A.1. Disk Format: Level 2A1 - Data Object Header Prefix</a></h3> + +<br /> +<h4><a name="V1ObjectHeaderPrefix"> +IV.A.1.a. Version 1 Data Object Header Prefix</a></h4> + + <p>Header messages are aligned on 8-byte boundaries for version 1 + object headers. + </p> + + <div align="center"> + <table class="format"> + <caption> + Version 1 Object Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Total Number of Header Messages</td> + </tr> + + <tr> + <td colspan="4">Object Reference Count</td> + </tr> + + <tr> + <td colspan="4">Object Header Size</td> + </tr> + + <tr> + <td colspan="2">Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + </tr> + + <tr> + <td>Header Message #1 Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td colspan="2">Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + </tr> + + <tr> + <td>Header Message #n Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + information in the object header. When the format of the + object header is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + is version one (1) (there was no version zero (0)) of the + object header. + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Header Messages</p></td> + <td> + <p>This value determines the total number of messages listed in + object headers for this object. This value includes the messages + in continuation messages for this object. + </p> + </td> + </tr> + + <tr> + <td><p>Object Reference Count</p></td> + <td> + <p>This value specifies the number of “hard links” to this object + within the current file. References to the object from external + files, “soft links” in this file and object references in this + file are not tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Size</p></td> + <td> + <p>This value specifies the number of bytes of header message data + following this length field that contain object header messages + for this object header. This value does not include the size of + object header continuation blocks for this object elsewhere in the + file. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>This value specifies the type of information included in the + following header message data. The message types for + header messages are defined in sections below. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size includes + padding bytes to make the message a multiple of eight + bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the message data is constant. This is used + for messages like the datatype message of a dataset. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the message is <em>shared</em> and stored + in another location than the object header. The Header + Message Data field contains a Shared Message + (described in the <a href="#ObjectHeaderMessages">Data Object Header Messages</a> + section below) + and the Size of Header Message Data field + contains the size of that Shared Message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, the message should not be shared. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, the HDF5 decoder should fail to open this object + if it does not understand the message’s type and the file + is open with permissions allowing write access to the file. + (Normally, unknown messages can just be ignored by HDF5 + decoders) + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, the HDF5 decoder should set bit 5 of this + message’s flags (in other words, this bit field) + if it does not understand the message’s type + and the object is modified in any way. (Normally, + unknown messages can just be ignored by HDF5 + decoders) + </td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, this object was modified by software that did not + understand this message. + (Normally, unknown messages should just be ignored by HDF5 + decoders) (Can be used to invalidate an index or a similar + feature) + </td> + </tr> + <tr> + <td align="center"><code>6</code></td> + <td>If set, this message is shareable. + </td> + </tr> + <tr> + <td align="center"><code>7</code></td> + <td>If set, the HDF5 decoder should always fail to open this + object if it does not understand the message’s type (whether + it is open for read-only or read-write access). (Normally, + unknown messages can just be ignored by HDF5 decoders) + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>The format and length of this field is determined by the + header message type and size respectively. Some header + message types do not require any data and this information + can be eliminated by setting the length of the message to + zero. The data is padded with enough zeroes to make the + size a multiple of eight. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="V2ObjectHeaderPrefix"> +IV.A.1.b. Version 2 Data Object Header Prefix</a></h4> + + <p>Note that the “total number of messages” field has been dropped from + the data object header prefix in this version. The number of messages + in the data object header is just determined by the messages encountered + in all the object header blocks.</p> + + <p>Note also that the fields and messages in this version of data object + headers have <em>no</em> alignment or padding bytes inserted - they are + stored packed together.</p> + + <div align="center"> + <table class="format"> + <caption> + Version 2 Object Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Access time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Modification Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Change Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Birth Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Maximum # of compact attributes <em>(optional)</em></td> + <td colspan="2">Minimum # of dense attributes <em>(optional)</em></td> + </tr> + + <tr> + <td>Size of Chunk #0 <em>(variable size)</em></td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>OHDR</code>” + is used to indicate the + beginning of an object header. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This field has a value of 2 indicating version 2 of the object header. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is a bit field indicating additional information + about the object header. + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>This two bit field determines the size of the + <em>Size of Chunk #0</em> field. The values are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The <em>Size of Chunk #0</em> field is 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The <em>Size of Chunk #0</em> field is 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The <em>Size of Chunk #0</em> field is 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The <em>Size of Chunk #0</em> field is 8 bytes. + </td> + </tr> + </table></p> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, attribute creation order is tracked.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, attribute creation order is indexed.</td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, non-default attribute storage phase change + values are stored.</td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, access, modification, change and birth times + are stored.</td> + </tr> + <tr> + <td align="center"><code>6-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Access Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s raw data was last accessed + (in other words, read or written). + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Modification Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after + the UNIX epoch when the object’s raw data was last + modified (in other words, written). + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Change Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s metadata was last changed. + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Birth Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object was created. + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum # of compact attributes</p></td> + <td> + <p>This is the maximum number of attributes to store in the compact + format before switching to the indexed format. + </p> + <p>This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Minimum # of dense attributes</p></td> + <td> + <p>This is the minimum number of attributes to store in the indexed + format before switching to the compact format. + </p> + <p>This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Chunk #0</p></td> + <td> + <p> + This unsigned value specifies the number of bytes of header + message data following this field that contain object header + information. + </p> + <p> + This value does not include the size of object header + continuation blocks for this object elsewhere in the file. + </p> + <p> + The length of this field varies depending on bits 0 and 1 of + the <em>flags</em> field. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size of messages + in this version does <em>not</em> include any padding bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in. + </p> + <p>This field is present if bit 2 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an + object header message prefix (message type + message size + + message flags). + </p> + <p>Gaps are formed when a message (typically an attribute message) + in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved + into the earlier chunk. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk. + </p> + </td> + </tr> + </table> + </div> + + <p>The header message types and the message data associated with + them compose the critical “metadata” about each object. Some + header messages are required for each object while others are + optional. Some optional header messages may also be repeated + several times in the header itself, the requirements and number + of times allowed in the header will be noted in each header + message description below. + </p> + + +<br /> +<h3><a name="ObjectHeaderMessages"> +IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> + + <p>Data object header messages are small pieces of metadata that are + stored in the data object header for each object in an HDF5 file. + Data object header messages provide the metadata required to describe + an object and its contents, as well as optional pieces of metadata + that annotate the meaning or purpose of the object. + </p> + + <p>Data object header messages are either stored directly in the data + object header for the object or are shared between multiple objects + in the file. When a message is shared, a flag in the <em>Message Flags</em> + indicates that the actual <em>Message Data</em> + portion of that message is stored in another location (such as another + data object header, or a heap in the file) and the <em>Message Data</em> + field contains the information needed to locate the actual information + for the message. + </p> + + <p> + The format of shared message data is described here:</p> + + <div align="center"> + <table class="format"> + <caption> + Shared Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in the format + of a shared object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6.1. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header + containing the message to be shared.</p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Shared Message (Version 2) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in the format + of a shared object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.1 and after. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header + containing the message to be shared.</p></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Shared Message (Version 3) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Location <em>(variable size)</em></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number indicates changes in the format of shared + object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8 and after. In this + version, the <em>Type</em> field can indicate that + the message is stored in the fractal heap. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message is not shared and is not shareable. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Message stored in file’s <em>shared object header message</em> + heap (a <em>shared</em> message). + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Message stored is not shared, but is sharable. + </td> + </tr> + + </table></p> + </td> + </tr> + + <tr> + <td><p>Location</p></td> + <td><p>This field contains either a <em>Size of Offsets</em>-bytes + address of the object header + containing the message to be shared, or an 8-byte fractal heap ID + for the message in the file’s <em>shared object header message</em> + heap. + </p> + </td> + </tr> + </table> + </div> + + + <p>The following is a list of currently defined header messages: + </p> + +<br /> +<h4><a name="NILMessage">IV.A.2.a. The NIL Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> NIL</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0000</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The NIL message is used to indicate a message which is to be + ignored when reading the header messages for a data object. + [Possibly one which has been deleted for some reason.] + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> Unspecified</td></tr> + </table></center> + <!-- end msgdesc table --> + + +<br /> +<h4><a name="DataspaceMessage">IV.A.2.b. The Dataspace Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Dataspace</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0001</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies according to the number of + dimensions, as described in the following table.</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset objects; + may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The dataspace message describes the number of dimensions (in + other words, “rank”) and size of each dimension that + the data object has. This message is only used for datasets which + have a simple, rectilinear, array-like layout; datasets requiring + a more complex layout are not yet supported. + </td> + </tr> + + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Dataspace Message - Version 1 + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4">Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #1<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #n<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + Dataspace Message. When the format of the + information in the message is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + document describes version one (1) (there was no version + zero (0)). + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data + object has. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. Bit 1 is used to indicate that + permutation indices are present. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + “<a href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. + If these values are not stored, the maximum size of each + dimension is assumed to be the dimension’s current size. + </p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. If these values are + not stored, the first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + </table> + </div> + + + + <br /> + <p>Version 2 of the dataspace message dropped the optional + permutation index value support, as it was never implemented in the + HDF5 Library:</p> + + <div align="center"> + <table class="format"> + <caption> + Dataspace Message - Version 2 + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Type</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + Dataspace Message. This field should be ‘2’ for version 2 + format messages. + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data object has. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of the dataspace: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A <em>scalar</em> dataspace; in other words, + a dataspace with a single, dimensionless element. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A <em>simple</em> dataspace; in other words, + a dataspace with a rank > 0 and an appropriate # of + dimensions. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>A <em>null</em> dataspace; in other words, + a dataspace with no elements. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + “<a href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. + If these values are not stored, the maximum size of each + dimension is assumed to be the dimension’s current size. + </p> + </td> + </tr> + + </table> + </div> + + + +<!-- +<br /> +<h4><a name="DataSpaceMessage">Header Message Name: Complex Dataspace (Fiber Bundle?)</a></h4> + + <!-- start msgdesc table -- + <center> + <table class="msgdesc"> + <p><b>Header Message Name: ???????</b></td></tr> + <b>Header Message Type: </b>0x0002<br /> + <b>Length:</b> Varies</td></tr> + + <b>Status:</b> One of the <em>Simple Dataspace</em> or + <em>Complex Dataspace</em> messages is required (but not both) and may + not be repeated.<br /> <b>Description:</b> The + <em>Dataspace</em> message describes space that the dataset is + mapped onto in a more comprehensive way than the <em>Simple + Dimensionality</em> message is capable of handling. The + dataspace of a dataset encompasses the type of coordinate system + used to locate the dataset’s elements as well as the structure and + regularity of the coordinate system. The dataspace also + describes the number of dimensions which the dataset inhabits as + well as a possible higher dimensional space in which the dataset + is located within. + + <br /> + <p><b>Format of Data:</b></p> + + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Message Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Mesh Type</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimensionality</td> + </tr> + </table> + </center> + + <br /> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br /> + The mesh type value is broken up as follows: <br /> + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Mesh-type Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1">Mesh Embedding</td> + <td colspan="1">Coordinate System</td> + <td colspan="1">Structure</td> + <td colspan="1">Regularity</td> + </tr> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset dataspace + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset’s dataspace is located within + another dataspace, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric datatype. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed:</p> + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + dataspace. + <br /> <br /> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Embedded Dimensionality Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Embedded Dimensionality</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #n</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #n</td> + </tr> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located within: in other words, a planar dataset + located within a 3-D space, a 3-D dataset + which is a subset of another 3-D space, and so on. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded dataspace + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset’s + origin within the embedded dataspace. + </dl> + </dl> + [Comment: need some way to handle different orientations of the + dataset dataspace + within the embedded dataspace]<br /> + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Regular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Logical Dimension Size #1</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Size #n</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #n</td> + </tr> + </table> + </center> + + <br /> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> + </dl> + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Irregular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #n</td> + </tr> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> + </tr> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #n</td> + </tr> + </table> + </center> + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Unstructured Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4"># of Grid Points</td> + </tr> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> + </tr> + <tr align="center"> + <td colspan="4">Grid Point Locations<br />.<br />.<br /></td> + </tr> + </table> + </center> +--> + +<br /> +<h4><a name="LinkInfoMessage">IV.A.2.c. The Link Info Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Link Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x002 </td></tr> + <tr><td colspan="2"><b>Length:</b> Varies </td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated. </td></tr> + <tr><td><b>Description:</b></td> + <td>The link info message tracks variable information about the + current state of the links for a “new style” + group’s behavior. Variable information will be stored in + this message and constant information will be stored in the + <a href="#GroupInfoMessage">Group Info</a> message. + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Link Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Creation Index <em>(8 bytes, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Name Index<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Creation Order Index<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field determines various optional aspects of the link + info message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, creation order for the links is tracked. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, creation order for the links is indexed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>This 64-bit value is the maximum creation order index value + stored for a link in this group.</p> + <p>This field is present if bit 0 of <em>flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td> + <p> + This is the address of the fractal heap to store dense links. + Each link stored in the fractal heap is stored as a + <a href="#LinkMessage">Link Message</a>. + </p> + <p> + If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Name Index</p></td> + <td><p>This is the address of the version 2 B-tree to index names of links.</p> + <p>If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Creation Order Index</p></td> + <td><p>This is the address of the version 2 B-tree to index creation order of links.</p> + <p>If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + <p>This field exists if bit 1 of <em>flags</em> is set.</p> + </td> + </tr> + + </table> + </div> + + +<br /> +<h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Datatype</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0003 + </td></tr> + <tr><td colspan="2"><b>Length:</b> Variable</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset or committed + datatype (formerly named datatype) objects; may not be repeated. + </td></tr> + <tr><td><b>Description:</b></td> + <td><p>The datatype message defines the datatype for each element + of a dataset or a common datatype for sharing between multiple + datasets. A datatype can describe an atomic type like a fixed- + or floating-point type or more complex types like a C struct + (compound datatype), array (array datatype) or C++ vector + (variable-length datatype).</p> + <p>Datatype messages that are part of a dataset object do not + describe how elements are related to one another; the dataspace + message is used for that purpose. Datatype messages that are part of + a committed datatype (formerly named datatype) message describe + a common datatype that can be shared by multiple datasets in the + file.</p> + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Datatype Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Class and Version</td> + <td>Class Bit Field, Bits 0-7</td> + <td>Class Bit Field, Bits 8-15</td> + <td>Class Bit Field, Bits 16-23</td> + </tr> + + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br /><br />Properties<br /><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Class and Version</p></td> + <td> + <p>The version of the datatype message and the datatype’s class + information are packed together in this field. The version + number is packed in the top 4 bits of the field and the class + is contained in the bottom 4 bits. + </p> + <p>The version number information is used for changes in the + format of the datatype message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Used by early versions of the library to encode + compound datatypes with explicit array fields. + See the compound datatype description below for + further details. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Used when an array datatype needs to be encoded. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Used when a VAX byte-ordered type needs to be + encoded. Packs various other datatype classes more + efficiently also. + </td> + </tr> + </table></p> + + <p>The class of the datatype determines the format for the class + bit field and properties portion of the datatype message, which + are described below. The + following classes are currently defined: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Fixed-Point</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Floating-Point</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Time</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>String</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>Bit field</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>Opaque</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>Compound</td> + </tr> + + <tr> + <td align="center"><code>7</code></td> + <td>Reference</td> + </tr> + + <tr> + <td align="center"><code>8</code></td> + <td>Enumerated</td> + </tr> + + <tr> + <td align="center"><code>9</code></td> + <td>Variable-Length</td> + </tr> + + <tr> + <td align="center"><code>10</code></td> + <td>Array</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Class Bit Fields</p></td> + <td> + <p>The information in these bit fields is specific to each datatype + class and is described below. All bits not defined for a + datatype class are set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>The size of a datatype element in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td> + <p>This variable-sized sequence of bytes encodes information + specific to each datatype class and is described for each class + below. If there is no property information specified for a + datatype class, the size of this field is zero bytes. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Fixed-Point Numbers (Class 0):</p> + + <div align="center"> + <table class="desc"> + <caption> + Fixed-point Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1, 2</p></td> + <td><p><b>Padding type.</b> Bit 1 is the lo_pad bit and bit 2 + is the hi_pad bit. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</p></td> + </tr> + + <tr> + <td><p>3</p></td> + <td><p><b>Signed.</b> If this bit is set then the fixed-point + number is in 2’s complement form.</p></td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Fixed-Point Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the fixed-point + value within the datatype. The bit offset specifies the number + of bits “to the right of” the value (which are set to the + lo_pad bit value). + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the fixed-point value + within the datatype. This value, combined with the datatype + element’s size and the Bit Offset field specifies the number + of bits “to the left of” the value (which are set to the + hi_pad bit value). + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Floating-Point Numbers (Class 1):</p> + + <div align="center"> + <table class="desc"> + <caption> + Floating-Point Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0, 6</p></td> + <td><p><b>Byte Order.</b> These two non-contiguous bits specify the + “endianness” of the bytes in the datatype element. + <table class="list"> + <tr> + <th width="10%" align="center">Bit 6</th> + <th width="10%" align="center">Bit 0</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td align="center"><code>0</code></td> + <td>Byte order is little-endian + </td> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is big-endian + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td align="center"><code>0</code></td> + <td>Reserved + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is VAX-endian + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>1, 2, 3</p></td> + <td><p><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 + is the high bits pad type, and bit 3 is the internal bits + pad type. If a datum has unused bits at either end or between + the sign bit, exponent, or mantissa, then the value of bit + 1, 2, or 3 is copied to those locations.</p></td> + </tr> + + <tr> + <td><p>4-5</p></td> + <td><p><b>Mantissa Normalization.</b> This 2-bit bit field specifies + how the most significant bit of the mantissa is managed. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>No normalization + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The most significant bit of the mantissa is always set + (except for 0.0). + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The most significant bit of the mantissa is not stored, + but is implied to be set. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>7</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + <tr> + <td><p>8-15</p></td> + <td><p><b>Sign Location.</b> This is the bit position of the sign + bit. Bits are numbered with the least significant bit zero.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Floating-Point Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + + <tr> + <td>Exponent Location</td> + <td>Exponent Size</td> + <td>Mantissa Location</td> + <td>Mantissa Size</td> + </tr> + + <tr> + <td colspan="4">Exponent Bias</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the floating-point + value within the datatype. The bit offset specifies the number + of bits “to the right of” the value. + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the floating-point value + within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Location</p></td> + <td> + <p>The bit position of the exponent field. Bits are numbered with + the least significant bit number zero. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Size</p></td> + <td> + <p>The size of the exponent field in bits. + </p> + </td> + </tr> + + <tr> + <td><p>Mantissa Location</p></td> + <td> + <p>The bit position of the mantissa field. Bits are numbered with + the least significant bit number zero. + </p> + </td> + </tr> + + <tr> + <td><p>Mantissa Size</p></td> + <td> + <p>The size of the mantissa field in bits. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Bias</p></td> + <td> + <p>The bias of the exponent field. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Time (Class 2):</p> + + + <div align="center"> + <table class="desc"> + <caption> + Time Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Time Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the time value. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Strings (Class 3):</p> + + + <div align="center"> + <table class="desc"> + <caption> + String Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Padding type.</b> This four-bit value determines the + type of padding to use for the string. The values are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Null Terminate: A zero byte marks the end of the + string and is guaranteed to be present after + converting a long string to a short string. When + converting a short string to a long string the value is + padded with additional null characters as necessary. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Null Pad: Null characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Space Pad: Space characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p><b>Character Set.</b> The character set used to + encode the string. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <p>There are no properties defined for the string class. + </p> + + + <p>Class specific information for bit fields (Class 4):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bitfield Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1, 2</p></td> + <td><p><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</p></td> + </tr> + + <tr> + <td><p>3-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Bit Field Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the bit field + within the datatype. The bit offset specifies the number + of bits “to the right of” the value. + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the bit field + within the datatype. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <p>Class specific information for Opaque (Class 5):</p> + + <div align="center"> + <table class="desc"> + <caption> + Opaque Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-7</p></td> + <td><p>Length of ASCII tag in bytes.</p></td> + </tr> + + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Opaque Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />ASCII Tag<br /> + <br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>ASCII Tag</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <p>Class specific information for Compound (Class 6):</p> + + <div align="center"> + <table class="desc"> + <caption> + Compound Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p><b>Number of Members.</b> This field contains the number + of members defined for the compound datatype. The member + definitions are listed in the Properties field of the data + type message.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + + <p>The Properties field of a compound datatype is a list of the + member definitions of the compound datatype. The member + definitions appear one after another with no intervening bytes. + The member types are described with a (recursively) encoded datatype + message.</p> + + <p>Note that the property descriptions are different for different + versions of the datatype version. Additionally note that the version + 0 datatype encoding is deprecated and has been replaced with later + encodings in versions of the HDF5 Library from the 1.4 release + onward.</p> + + + <div align="center"> + <table class="format"> + <caption> + Compound Properties Description for Datatype Version 1 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension Permutation</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #2 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #3 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #4 Size (required)</td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>If set to zero, this field indicates a scalar member. If set + to a value greater than zero, this field indicates that the + member is an array of values. For array members, the size of + the array is indicated by the ‘Size of Dimension n’ field in + this message. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension Permutation</p></td> + <td> + <p>This field was intended to allow an array field to have + its dimensions permuted, but this was never implemented. + This field should always be set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This field is the size of a dimension of the array field as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Compound Properties Description for Datatype Version 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Compound Properties Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>This NUL-terminated string provides a description for the + opaque type. It is <em>not</em> NUL-padded to a multiple of 8 + bytes.</p></td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td><p>This is the byte offset of the member within the datatype. + The field size is the minimum number of bytes necessary, + based on the size of the datatype element. For example, a + datatype element size of less than 256 bytes uses a 1 byte + length, a datatype element size of 256-65535 bytes uses a + 2 byte length, and so on.</p></td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td><p>This field is a datatype message describing the datatype of + the member.</p></td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Reference (Class 7):</p> + + <div align="center"> + <table class="desc"> + <caption> + Reference Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Type.</b> This four-bit value contains the type of reference + described. The values defined are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Object Reference: A reference to another object in this + HDF5 file. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Dataset Region Reference: A reference to a region within + a dataset in this HDF5 file. + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <p>There are no properties defined for the reference class. + </p> + + + <br /> + <p>Class specific information for Enumeration (Class 8):</p> + + <div align="center"> + <table class="desc"> + <caption> + Enumeration Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p><b>Number of Members.</b> The number of name/value + pairs defined for the enumeration type.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Enumeration Property Description for Datatype Versions 1 & 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually an + integer. The information for that parent type is described + recursively by this field. + </p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p>The name for each name/value pair. Each name is stored as a null + terminated ASCII string in a multiple of eight bytes. The names + are in no particular order. + </p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value + is determined by the parent type. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Enumeration Property Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually an + integer. The information for that parent type is described + recursively by this field. + </p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p>The name for each name/value pair. Each name is stored as a null + terminated ASCII string, <em>not</em> padded to a multiple of + eight bytes. The names are in no particular order. + </p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value + is determined by the parent type. + </p> + </td> + </tr> + + </table> + </div> + + + + <br /> + <p>Class specific information for Variable-Length (Class 9):</p> + + <div align="center"> + <table class="desc"> + <caption> + Variable-Length Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Type.</b> This four-bit value contains the type of + variable-length datatype described. The values defined are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Sequence: A variable-length sequence of any datatype. + Variable-length sequences do not have padding or + character set information. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>String: A variable-length sequence of characters. + Variable-length strings have padding and character set + information. + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p><b>Padding type.</b> (variable-length string only) + This four-bit value determines the type of padding + used for variable-length strings. The values are the same + as for the string padding type, as follows: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Null terminate: A zero byte marks the end of a string + and is guaranteed to be present after converting a long + string to a short string. When converting a short string + to a long string, the value is padded with additional null + characters as necessary. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Null pad: Null characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Space pad: Space characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + <p>This value is set to zero for variable-length sequences.</p> + + </td> + </tr> + + <tr> + <td><p>8-11</p></td> + <td><p><b>Character Set.</b> (variable-length string only) + This four-bit value specifies the character set + to be used for encoding the string: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + <p>This value is set to zero for variable-length sequences.</p> + + </td> + </tr> + + <tr> + <td><p>12-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Variable-Length Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="10%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each variable-length type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <p>Class specific information for Array (Class 10):</p> + + <p>There are no bit fields defined for the array class. + </p> + + <p>Note that the dimension information defined in the property for this + datatype class is independent of dataspace information for a dataset. + The dimension information here describes the dimensionality of the + information within a data element (or a component of an element, if the + array datatype is nested within another datatype) and the dataspace for a + dataset describes the size and locations of the elements in a dataset. + </p> + + + <div align="center"> + <table class="format"> + <caption> + Array Property Description for Datatype Version 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Permutation Index #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Permutation Index #n</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array + as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. Currently, dimension + permutations are not supported, and these indices should + be set to the index position minus one. In other words, + the first dimension should be set to 0, the second dimension + should be set to 1, and so on. + </p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Array Property Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array + as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + + +<br /> +<h4><a name="OldFillValueMessage">IV.A.2.e. The Data Storage - +Fill Value (Old) Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Fill Value + (old)</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0004</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The fill value message stores a single data value which + is returned to the application when an uninitialized data element + is read from a dataset. The fill value is interpreted with the + same datatype as the dataset. If no fill value message is present + then a fill value of all zero bytes is assumed.</p> + <p>This fill value message is deprecated in favor of the + “new” fill value message (Message Type 0x0005) and + is only written to the file for forward compatibility with + versions of the HDF5 Library before the 1.6.0 version. + Additionally, it only appears for datasets with a user-defined + fill value (as opposed to the library default fill value or an + explicitly set “undefined” fill value).</p> + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Fill Value Message (Old) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. + </p> + </td> + </tr> + </table> + </div> + + +<br /> +<h4><a name="FillValueMessage">IV.A.2.f. The Data Storage - +Fill Value Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Fill + Value</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0005</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset objects; + may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The fill value message stores a single data value which is + returned to the application when an uninitialized data element + is read from a dataset. The fill value is interpreted with the + same datatype as the dataset.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Fill Value Message - Versions 1 & 2 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Space Allocation Time</td> + <td>Fill Value Write Time</td> + <td>Fill Value Defined</td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Initial version of this message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are + only present if the Fill Value Defined field is set + to 1. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message + more efficiently than version 2. + </td> + </tr> + </table></p> + </p> + </td> + </tr> + + <tr> + <td><p>Space Allocation Time</p></td> + <td> + <p>When the storage space for the dataset’s raw data will be + allocated. The allowed values are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Not used. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Early allocation. Storage space for the entire dataset + should be allocated in the file when the dataset is + created. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Late allocation. Storage space for the entire dataset + should not be allocated until the dataset is written + to. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Incremental allocation. Storage space for the + dataset should not be allocated until the portion + of the dataset is written to. This is currently + used in conjunction with chunked data storage for + datasets. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Fill Value Write Time</p></td> + <td> + <p>At the time that storage space for the dataset’s raw data is + allocated, this value indicates whether the fill value should + be written to the raw data storage elements. The allowed values + are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>On allocation. The fill value is always written to + the raw data storage when the storage space is allocated. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Never. The fill value should never be written to + the raw data storage. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Fill value written if set by user. The fill value + will be written to the raw data storage when the storage + space is allocated only if the user explicitly set + the fill value. If the fill value is the library + default or is undefined, it will not be written to + the raw data storage. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Fill Value Defined</p></td> + <td> + <p>This value indicates if a fill value is defined for this + dataset. If this value is 0, the fill value is undefined. + If this value is 1, a fill value is defined for this dataset. + For version 2 or later of the fill value message, this value + controls the presence of the Size and Fill Value fields. + </p> + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, + and the Fill Value Defined field is set to 0. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is + not present if the Version field is greater than 1, + and the Fill Value Defined field is set to 0. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Fill Value Message - Version 3 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Initial version of this message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are + only present if the Fill Value Defined field is set + to 1. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message + more efficiently than version 2. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>When the storage space for the dataset’s raw data will be + allocated. The allowed values are: + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>Space Allocation Time, with the same + values as versions 1 and 2 of the message. + </td> + </tr> + <tr> + <td align="center"><code>2-3</code></td> + <td>Fill Value Write Time, with the same + values as versions 1 and 2 of the message. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Fill Value Undefined, indicating that the fill + value has been marked as “undefined” for this dataset. + Bits 4 and 5 cannot both be set. + </td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>Fill Value Defined, with the same values as + versions 1 and 2 of the message. + Bits 4 and 5 cannot both be set. + </td> + </tr> + <tr> + <td align="center"><code>6-7</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, + and the Fill Value Defined flag is set to 0. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is + not present if the Version field is greater than 1, + and the Fill Value Defined flag is set to 0. + </p> + </td> + </tr> + </table> + </div> + + +<br /> +<h4><a name="LinkMessage">IV.A.2.g. The Link Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Link</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0006</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies </td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated. </td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message encodes the information for a link in a + group’s object header, when the group is storing its links + “compactly”, or in the group’s fractal heap, + when the group is storing its links “densely”.</p> + <p>A group is storing its links compactly when the fractal heap + address in the <em><a href="#LinkInfoMessage">Link Info + Message</a></em> is set to the “undefined address” + value.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Link Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td>Link type <em>(optional)</em></td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Creation Order <em>(8 bytes, optional)</em><br /><br /></td> + </tr> + <tr> + <td>Link Name Character Set <em>(optional)</em></td> + <td>Length of Link Name (variable size)</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Link Name (variable size)</td> + </tr> + <tr> + <td colspan="4"><br />Link Information (variable size)<br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 1.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field contains information about the link and controls + the presence of other fields below. + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>Determines the size of the <em>Length of Link Name</em> + field. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 8 bytes. + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Creation Order Field Present: if set, the <em>Creation + Order</em> field is present. If not set, creation order + information is not stored for links in this group. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Link Type Field Present: if set, the link is not + a hard link and the <em>Link Type</em> field is present. + If not set, the link is a hard link. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Link Name Character Set Field Present: if set, the + link name is not represented with the ASCII character + set and the <em>Link Name Character Set</em> field is + present. If not set, the link name is represented with + the ASCII character set. + </td> + </tr> + <tr> + <td align="center"><code>5-7</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Link type</p></td> + <td><p>This is the link class type and can be one of the following + values: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A hard link (should never be stored in the file) + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A soft link. + </td> + </tr> + <tr> + <td align="center"><code>2-63</code></td> + <td>Reserved for future HDF5 internal use. + </td> + </tr> + <tr> + <td align="center"><code>64</code></td> + <td>An external link. + </td> + </tr> + <tr> + <td align="center"><code>65-255</code></td> + <td>Reserved, but available for user-defined link types. + </td> + </tr> + </table></p> + + <p>This field is present if bit 3 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td><p>This 64-bit value is an index of the link’s creation time within + the group. Values start at 0 when the group is created an increment + by one for each link added to the group. Removing a link from a + group does not change existing links’ creation order field. + </p> + <p>This field is present if bit 2 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Link Name Character Set</p></td> + <td><p>This is the character set for encoding the link’s name: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding (this should never be stored + in the file) + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + </table></p> + + <p>This field is present if bit 4 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Length of link name</p></td> + <td><p>This is the length of the link’s name. The size of this field + depends on bits 0 and 1 of <em>Flags</em>.</p> + </td> + </tr> + + <tr> + <td><p>Link name</p></td> + <td><p>This is the name of the link, non-NULL terminated.</p> + </td> + </tr> + + <tr> + <td><p>Link information</p></td> + <td><p>The format of this field depends on the <em>link type</em>.</p> + <p>For <b>hard</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%"><i>Size of Offsets</i> bytes:</td> + <td width="80%">The address of the object header for the object that the + link points to. + </td> + </tr> + </table> + </p> + + <p> + For <b>soft</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of soft link value.</td> + </tr> + <tr> + <td><em>Length of soft link value</em> bytes:</td> + <td>A non-NULL-terminated string storing the value of the + soft link. + </td> + </tr> + </table> + </p> + + <p> + For <b>external</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of external link value.</td> + </tr> + <tr> + <td><em>Length of external link value</em> bytes:</td> + <td>The first byte contains the version number in the + upper 4 bits and flags in the lower 4 bits for the external + link. Both version and flags are defined to be zero in + this document. The remaining bytes consist of two + NULL-terminated strings, with no padding between them. + The first string is the name of the HDF5 file containing + the object linked to and the second string is the full path + to the object linked to, within the HDF5 file’s + group hierarchy. + </td> + </tr> + </table> + </p> + + <p> + For <b>user-defined</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of user-defined data.</td> + </tr> + <tr> + <td><em>Length of user-defined link value</em> bytes:</td> + <td>The data supplied for the user-defined link type.</td> + </tr> + </table> + </p> + + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="ExternalFileListMessage">IV.A.2.h. The Data Storage - +External Data Files Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> External + Data Files</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0007</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The external data storage message indicates that the data + for an object is stored outside the HDF5 file. The filename of + the object is stored as a Universal Resource Location (URL) of + the actual filename containing the data. An external file list + record also contains the byte offset of the start of the data + within the file and the amount of space reserved in the file + for that data.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + External File List Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="2">Allocated Slots</td> + <td colspan="2">Used Slots</td> + </tr> + + <tr> + <td colspan="4"><br />Heap Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Slot Definitions...<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of + External Data Storage Message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The current version used by the library.</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Allocated Slots</p></td> + <td> + <p>The total number of slots allocated in the message. Its value must be at least as + large as the value contained in the Used Slots field. (The current library simply + uses the number of Used Slots for this message)</p> + </td> + </tr> + + <tr> + <td><p>Used Slots</p></td> + <td> + <p>The number of initial slots which contains valid information.</p> + </td> + </tr> + + <tr> + <td><p>Heap Address</p></td> + <td> + <p>This is the address of a local heap which contains the names for the external + files (The local heap information can be found in Disk Format Level 1D in this + document). The name at offset zero in the heap is always the empty string.</p> + </td> + </tr> + + <tr> + <td><p>Slot Definitions</p></td> + <td> + <p>The slot definitions are stored in order according to the array addresses they + represent.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + External File List Slot + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name Offset in Local Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset in External Data File<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Size in External File<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name Offset in Local Heap</p></td> + <td> + <p>The byte offset within the local name heap for the name + of the file. File names are stored as a URL which has a + protocol name, a host name, a port number, and a file + name: + <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. + If the protocol is omitted then “file:” is assumed. If + the port number is omitted then a default port for that + protocol is used. If both the protocol and the port + number are omitted then the colon can also be omitted. If + the double slash and host name are omitted then + “localhost” is assumed. The file name is the only + mandatory part, and if the leading slash is missing then + it is relative to the application’s current working + directory (the use of relative names is not + recommended). + </p> + </td> + </tr> + + <tr> + <td><p>Offset in External Data File</p></td> + <td> + <p>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single + dataset this will usually be zero.</p> + </td> + </tr> + + <tr> + <td><p>Data Size in External File</p></td> + <td> + <p>This is the total number of bytes reserved in the + specified file for raw data storage. For a file that + contains exactly one complete dataset which is not + extendable, the size will usually be the exact size of the + dataset. However, by making the size larger one allows + HDF5 to extend the dataset. The size can be set to a value + larger than the entire file since HDF5 will read zeroes + past the end of the file without failing.</p> + </td> + </tr> + </table> + </div> + + +<br /> +<h4><a name="LayoutMessage">IV.A.2.i. The Data Storage - Layout +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Data Storage - + Layout</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0008</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for datasets; may not + be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>Data layout describes how the elements of a multi-dimensional + array are stored in the HDF5 file. Three types of data layout + are supported: + <ol> + <li>Contiguous: The array is stored in one contiguous area of + the file. This layout requires that the size of the array be + constant: data manipulations such as chunking, compression, + checksums, or encryption are not permitted. The message stores + the total storage size of the array. The offset of an element + from the beginning of the storage area is computed as in a C + array.</li> + <li>Chunked: The array domain is regularly decomposed into + chunks, and each chunk is allocated and stored separately. This + layout supports arbitrary element traversals, compression, + encryption, and checksums. (these features are described + in other messages). The message stores the size of a chunk + instead of the size of the entire array; the storage size of + the entire array can be calculated by traversing the B-tree + that stores the chunk addresses.</li> + <li>Compact: The array is stored in one contiguous block, as + part of this object header message.</li> + </ol></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Data Layout Message (Versions 1 and 2) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Layout Class</td> + <td>Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Data Address<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Dimension 0 Size</td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Dataset Element Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Compact Data Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Compact Data... <em>(variable size, optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of the data + layout message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by version 1.4 and before of the library to encode layout information. + Data space is always allocated when the data set is created.</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by version 1.6.x of the library to encode layout information. + Data space is allocated only when it is necessary.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the + message. The value stored for chunked storage is 1 greater than + the number of dimensions in the dataset’s dataspace. + For example, 2 is stored for a 1 dimensional dataset. + </p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for the data + and how the other fields of the layout message are to be + interpreted. + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Data Address</p></td> + <td><p>For contiguous storage, this is the address of the raw + data in the file. For chunked storage this is the address + of the v1 B-tree that is used to look up the addresses of the + chunks. This field is not present for compact storage. + If the version for this message is greater than 1, the address + may have the “undefined address” value, to indicate that + storage has not yet been allocated for this array.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>For contiguous and compact storage the dimensions define + the entire size of the array while for chunked storage they define + the size of a single chunk. In all cases, they are in units of + array elements (not bytes). The first dimension stored in the list + of dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes. This field is only + present for chunked storage. + </p> + </td> + </tr> + + <tr> + <td><p>Compact Data Size</p></td> + <td><p>This field is only present for compact data storage. + It contains the size of the raw data for the dataset array, in + bytes.</p> + </td> + </tr> + + <tr> + <td><p>Compact Data</p></td> + <td><p>This field is only present for compact data storage. + It contains the raw data for the dataset array.</p> + </td> + </tr> + </table> + </div> + + <br /> + <p>Version 3 of this message re-structured the format into specific + properties that are required for each layout class.</p> + + + <div align="center"> + <table class="format"> + <caption> + <b>Data Layout Message (Version 3)</b> + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Layout Class</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Properties <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of layout message + and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the version 1.6.3 and later of the library to store properties + for each layout class.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for the data + and how the other fields of the layout message are to be + interpreted. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td><p>This variable-sized field encodes information specific to each + layout class and is described below. If there is no property + information specified for a layout class, the size of this field + is zero bytes.</p></td> + </tr> + </table> + </div> + + <br /> + <p>Class-specific information for compact layout (Class 0): (Note: The dimensionality information + is in the Dataspace message)</p> + + + <div align="center"> + <table class="format"> + <caption> + Compact Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Raw Data... <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size of the raw data for the dataset + array, in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Raw Data</p></td> + <td><p>This field contains the raw data for the dataset array.</p></td> + </tr> + </table> + </div> + + + <br /> + <p>Class-specific information for contiguous layout (Class 1): (Note: The dimensionality information + is in the Dataspace message)</p> + + + <div align="center"> + <table class="format"> + <caption> + Contiguous Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the raw data in the file. + The address may have the “undefined address” value, to indicate + that storage has not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size allocated to store the raw data, + in bytes. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <p>Class-specific information for chunked layout (Class 2):</p> + + + <div align="center"> + <table class="format"> + <caption> + Chunked Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Dimension 0 Size</td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Dataset Element Size</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>A chunk has a fixed dimensionality. This field specifies + the number of dimension size fields later in the message.</p></td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the v1 B-tree that is used to look up the + addresses of the chunks that actually store portions of the array + data. The address may have the “undefined address” value, to + indicate that storage has not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>These values define the dimension size of a single chunk, in + units of array elements (not bytes). The first dimension stored in + the list of dimensions is the slowest changing dimension and the + last dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="BogusMessage">IV.A.2.j. The Bogus Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Bogus</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0009</td></tr> + <tr><td colspan="2"><b>Length:</b> 4 bytes</td></tr> + <tr><td colspan="2"><b>Status:</b> For testing only; should never + be stored in a valid file.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message is used for testing the HDF5 Library’s + response to an “unknown” message type and should + never be encountered in a valid HDF5 file.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Bogus Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Bogus Value</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bogus Value</p></td> + <td> + <p>This value should always be: <code>0xdeadbeef</code>.</p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="GroupInfoMessage">IV.A.2.k. The Group Info Message +</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Group Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000A</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message stores information for the constants defining + a “new style” group’s behavior. Constant + information will be stored in this message and variable + information will be stored in the + <a href="#LinkInfoMessage">Link Info</a> message.</p> + <p>Note: the “estimated entry” information below is + used when determining the size of the object header for the + group when it is created.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Group Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Link Phase Change: Maximum Compact Value <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Link Phase Change: Minimum Dense Value <em>(optional)</em></td> + <td colspan="2">Estimated Number of Entries <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Estimated Link Name Length of Entries <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the group information flag with the following definition: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, link phase change values are stored. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the estimated entry information is non-default + and is stored. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Link Phase Change: Maximum Compact Value</p></td> + <td><p>The is the maximum number of links to store “compactly” (in + the group’s object header).</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Link Phase Change: Minimum Dense Value</p></td> + <td><p>This is the minimum number of links to store “densely” (in + the group’s fractal heap). The fractal heap’s address is + located in the <a href="#LinkInfoMessage">Link Info</a> + message.</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Estimated Number of Entries</p></td> + <td><p>This is the estimated number of entries in groups.</p> + <p>If this field is not present, the default value of <code>4</code> + will be used for the estimated number of group entries.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Estimated Link Name Length of Entries</p></td> + <td><p>This is the estimated length of entry name.</p> + <p>If this field is not present, the default value of <code>8</code> + will be used for the estimated link name length of group entries.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + </table> + </div> + </p> + +<br /> +<h4><a name="FilterMessage">IV.A.2.l. The Data Storage - Filter +Pipeline Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> + Data Storage - Filter Pipeline</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000B</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message describes the filter pipeline which should + be applied to the data stream by providing filter identification + numbers, flags, a name, and client data.</p> + <p>This message may be present in the object headers of both + dataset and group objects. For datasets, it specifies the + filters to apply to raw data. For groups, it specifies the + filters to apply to the group’s fractal heap. Currently, + only datasets using chunked data storage use the filter + pipeline on their raw data.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Filter Pipeline Message - Version 1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 1.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a + message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Filter Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length</td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Padding <em>(variable size, optional)</em></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, + is designed to be a unique identifier for the filter. + Values from zero through 32,767 are reserved for filters + supported by The HDF Group in the HDF5 Library and for + filters requested and supported by third parties. + Filters supported by The HDF Group are documented immediately + below. Information on 3rd-party filters can be found at + The HDF Group’s + <a href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page.</p> + + <p> + To request a filter identifier, please contact + The HDF Group’s Help Desk at + <img src="Graphics/help.png" valign="middle" height="14" + alt="The HDF Group Help Desk">. + You will be asked to provide the following information:</p> + <ol> + <li>Contact information for the developer requesting the + new identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p> + Values from 32768 to 65535 are reserved for non-distributed uses + (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p> + The filters currently in library version 1.8.0 are + listed below: + + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + </p></td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. The + bit values defined so far are: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently skipped in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p>Each filter can store integer values to control + how the filter operates. The number of entries in the + <em>Client Data</em> array is stored in this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>If the <em>Name Length</em> field is non-zero then it will + contain the size of this field, padded to a multiple of eight. This + field contains a null-terminated, ASCII character + string to serve as a comment/name for the filter.</p></td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p>This is an array of four-byte integers which will be + passed to the filter function. The <em>Client Data Number</em> of + Values determines the number of elements in the array.</p></td> + </tr> + + <tr> + <td><p>Padding</p></td> + <td><p>Four bytes of zeroes are added to the message at this + point if the Client Data Number of Values field contains + an odd number.</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Filter Pipeline Message - Version 2 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 2.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a + message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Filter Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, + is designed to be a unique identifier for the filter. + Values from zero through 32,767 are reserved for filters + supported by The HDF Group in the HDF5 Library and for + filters requested and supported by third parties. + Filters supported by The HDF Group are documented immediately + below. Information on 3rd-party filters can be found at + The HDF Group’s + <a href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page.</p> + + <p> + To request a filter identifier, please contact + The HDF Group’s Help Desk at + <img src="Graphics/help.png" valign="middle" height="14" + alt="The HDF Group Help Desk">. + You will be asked to provide the following information:</p> + <ol> + <li>Contact information for the developer requesting the + new identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p> + Values from 32768 to 65535 are reserved for non-distributed uses + (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p> + The filters currently in library version 1.8.0 are + listed below: + + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + </p></td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</p> + <p>Filters with IDs less than 256 (in other words, filters + that are defined in this format documentation) do not store + the <em>Name Length</em> or <em>Name</em> fields. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. The + bit values defined so far are: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently skipped in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p>Each filter can store integer values to control + how the filter operates. The number of entries in the + <em>Client Data</em> array is stored in this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>If the <em>Name Length</em> field is non-zero then it will + contain the size of this field, <em>not</em> padded to a multiple + of eight. This field contains a <em>non-</em>null-terminated, + ASCII character string to serve as a comment/name for the filter. + </p> + <p>Filters that are defined in this format documentation + such as deflate and shuffle do not store the <em>Name + Length</em> or <em>Name</em> fields. + </p> + </td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p>This is an array of four-byte integers which will be + passed to the filter function. The Client Data Number of + Values</em> determines the number of elements in the array.</p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="AttributeMessage">IV.A.2.m. The Attribute Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Attribute</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000C</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The <em>Attribute</em> message is used to store objects + in the HDF5 file which are used as attributes, or + “metadata” about the current object. An attribute + is a small dataset; it has a name, a datatype, a dataspace, and + raw data. Since attributes are stored in the object header, they + should be relatively small (in other words, less than 64KB). + They can be associated with any type of object which has an + object header (groups, datasets, or committed (named) + 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"> + “Special Issues”</a> section of the Attributes chapter + in the <cite>HDF5 User’s 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. + Attributes on different objects may have the same name, + however.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Attribute Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the format of the + attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6 to encode attribute message. + This version does not support shared datatypes.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator. Note that the <em>Name</em> field below may + contain additional padding not represented by this + field.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below. Note that the <em>Datatype</em> field may contain + additional padding not represented by this field.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below. Note that the <em>Dataspace</em> field may contain + additional padding not represented by this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is + padded with additional null characters to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. This + field is <em>not</em> padded with additional bytes.</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Attribute Message (Version 2) + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the + format of the attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.x and after to encode + attribute messages. + This version supports shared datatypes. The fields of + name, datatype, and dataspace are not padded with + additional bytes of zero. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s datatype is + shared, this field will contain a “shared message” encoding + instead of the datatype encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s dataspace is + shared, this field will contain a “shared message” encoding + instead of the dataspace encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes.</p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. + </p> + <p>This field is <em>not</em> padded with additional zero bytes. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Attribute Message (Version 3) + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td>Name Character Set Encoding</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the + format of the attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8.x and after to + encode attribute messages. + This version supports attributes with non-ASCII names. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Name Character Set Encoding</p></td> + <td><p>The character set encoding for the attribute’s name: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s datatype is + shared, this field will contain a “shared message” encoding + instead of the datatype encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s dataspace is + shared, this field will contain a “shared message” encoding + instead of the dataspace encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes.</p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. + </p> + <p>This field is <em>not</em> padded with additional zero bytes. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="CommentMessage">IV.A.2.n. The Object Comment +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Comment</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000D</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object comment is designed to be a short description of + an object. An object comment is a sequence of non-zero + (<code>\0</code>) ASCII characters with no other formatting + included by the library.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Name Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Comment <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>A null terminated ASCII character string.</p></td> + </tr> + </table> + </div> + +<br /> +<h4><a name="OldModificationTimeMessage">IV.A.2.o. The Object +Modification Time (Old) Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Modification Time (Old)</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000E</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The object modification date and time is a timestamp + which indicates (using ISO-8601 date and time format) the last + modification of an object. The time is updated when any object + header message changes according to the system clock where the + change was posted. All fields of this message should be + interpreted as coordinated universal time (UTC).</p> + <p>This modification time message is deprecated in favor of + the “new” <a href="#ModificationTimeMessage">Object + Modification Time</a> message and is no longer written to the + file in versions of the HDF5 Library after the 1.6.0 + version.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Modification Time Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Year</td> + </tr> + + <tr> + <td colspan="2">Month</td> + <td colspan="2">Day of Month</td> + </tr> + + <tr> + <td colspan="2">Hour</td> + <td colspan="2">Minute</td> + </tr> + + <tr> + <td colspan="2">Second</td> + <td colspan="2">Reserved</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Year</p></td> + <td><p>The four-digit year as an ASCII string. For example, + <code>1998</code>. + </p></td> + </tr> + + <tr> + <td><p>Month</p></td> + <td><p>The month number as a two digit ASCII string where + January is <code>01</code> and December is <code>12</code>.</p></td> + </tr> + + <tr> + <td><p>Day of Month</p></td> + <td><p>The day number within the month as a two digit ASCII + string. The first day of the month is <code>01</code>.</p></td> + </tr> + + <tr> + <td><p>Hour</p></td> + <td><p>The hour of the day as a two digit ASCII string where + midnight is <code>00</code> and 11:00pm is <code>23</code>.</p></td> + </tr> + + <tr> + <td><p>Minute</p></td> + <td><p>The minute of the hour as a two digit ASCII string where + the first minute of the hour is <code>00</code> and + the last is <code>59</code>.</p></td> + </tr> + + <tr> + <td><p>Second</p></td> + <td><p>The second of the minute as a two digit ASCII string + where the first second of the minute is <code>00</code> + and the last is <code>59</code>.</p></td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td><p>This field is reserved and should always be zero.</p></td> + </tr> + </table> + </div> + +<br /> +<h4><a name="SOHMTableMessage">IV.A.2.p. The Shared Message Table +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Shared Message + Table</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000F</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message is used to locate the table of shared object + header message (SOHM) indexes. Each index consists of information + to find the shared messages from either the heap or object header. + This message is <em>only</em> found in the superblock + extension.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Shared Message Table Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Shared Object Header Message Table Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td>Number of Indices</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 0.</p></td> + </tr> + + <tr> + <td><p>Shared Object Header Message Table Address</p></td> + <td><p>This field is the address of the master table for shared + object header message indexes.</p> + </td> + </tr> + + <tr> + <td><p>Number of Indices</p></td> + <td><p>This field is the number of indices in the master table. + </p></td> + </tr> + + </table> + </div> + +<br /> +<h4><a name="ContinuationMessage">IV.A.2.q. The Object Header +Continuation Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object Header + Continuation</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0010</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object header continuation is the location in the file + of a block containing more header messages for the current data + object. This can be used when header blocks become too large or + are likely to change over time.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Object Header Continuation Message + </caption> + + <tr> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Offset<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Offset</p></td> + <td><p>This value is the address in the file where the + header continuation block is located.</p></td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This value is the length in bytes of the header continuation + block in the file.</p></td> + </tr> + </table> + </div> + <br /> + + <p>The format of the header continuation block that this message points + to depends on the version of the object header that the message is + contained within. + </p> + + <p> + Continuation blocks for version 1 object headers have no special + formatting information; they are merely a list of object header + message info sequences (type, size, flags, reserved bytes and data + for each message sequence). See the description + of <a href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix.</a> + </p> + + <p>Continuation blocks for version 2 object headers <em>do</em> have + special formatting information as described here + (see also the description of + <a href="#V2ObjectHeaderPrefix">Version 2 Data Object Header Prefix.</a>): + </p> + <div align="center"> + <table class="format"> + <caption> + Version 2 Object Header Continuation Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>OCHK</code>” + is used to indicate the + beginning of an object header continuation block. This gives file + consistency checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in.</p> + <p>This field is present if bit 2 of <em>flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an + object header message prefix (message type + message size + + message flags).</p> + <p>Gaps are formed when a message (typically an attribute message) + in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved + into the earlier chunk.</p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk. + </p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="SymbolTableMessage">IV.A.2.r. The Symbol Table +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Symbol Table + Message</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0011</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for + “old style” groups; may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>Each “old style” group has a v1 B-tree and a + local heap for storing symbol table entries, which are located + with this message.</td></tr> + <tr><td colspan="2"><b>Format of data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + <b>Symbol Table Message</b> + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />v1 B-tree Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Local Heap Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>v1 B-tree Address</p></td> + <td><p>This value is the address of the v1 B-tree containing the + symbol table entries for the group.</p></td> + </tr> + + <tr> + <td><p>Local Heap Address</p></td> + <td><p>This value is the address of the local heap containing + the link names for the symbol table entries for the group.</p></td> + </tr> + </table> + </div> + +<br /> +<h4><a name="ModificationTimeMessage">IV.A.2.s. The Object +Modification Time Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Modification Time</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0012</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object modification time is a timestamp which indicates + the time of the last modification of an object. The time is + updated when any object header message changes according to + the system clock where the change was posted.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Modification Time Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Seconds After UNIX Epoch</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used for changes in the format of Object Modification Time + and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by Version 1.6.1 and after of the library to encode time. In + this version, the time is the seconds after Epoch.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Seconds After UNIX Epoch</p></td> + <td><p>A 32-bit unsigned integer value that stores the number of + seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, + Coordinated Universal Time.</p></td> + </tr> + </table> + </div> + +<br /> +<h4><a name="BtreeKValuesMessage">IV.A.2.t. The B-tree +‘K’ Values Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> B-tree + ‘K’ Values</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0013</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message retrieves non-default ‘K’ values + for internal and leaf nodes of a group or indexed storage v1 + B-trees. This message is <em>only</em> found in the superblock + extension.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + B-tree ‘K’ Values Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="2">Indexed Storage Internal Node K</td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Group Internal Node K</td> + <td colspan="2">Group Leaf Node K</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each internal node of an + indexed storage v1 B-tree. See the description of this field + in version 0 and 1 of the superblock as well the section on + v1 B-trees. + </p> + </td> + </tr> + + <tr> + <td><p>Group Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each internal node of a group + v1 B-tree. See the description of this field in version 0 and + 1 of the superblock as well as the section on v1 B-trees. + </p> + </td> + </tr> + + <tr> + <td><p>Group Leaf Node K</p></td> + <td><p>This is the node ‘K’ value for each leaf node of a group v1 + B-tree. See the description of this field in version 0 and 1 + of the superblock as well as the section on v1 B-trees. + </p> + </td> + </tr> + + </table> + </div> + +<br /> +<h4><a name="DrvInfoMessage">IV.A.2.u. The Driver Info +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Driver + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0014</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + + <tr><td> + <b>Description:</b></td> + <td>This message contains information needed by the file driver + to reopen a file. This message is <em>only</em> found in the + superblock extension: see the <a href="#SuperblockExt"> + “Disk Format: Level 0C - Superblock Extension”</a> + section for more information. For more information on the fields + in the driver info message, see the <a href="#DriverInfo"> + “Disk Format : Level 0B - File Driver Info”</a> + section; those who use the multi and family file drivers will + find this section particularly helpful.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Driver Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Driver Identification</td> + </tr> + + <tr> + <td colspan="2">Driver Information Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Driver Information <em>(variable size)</em><br /><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td><p>This is an eight-byte ASCII string without null termination which + identifies the driver. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td><p>The size in bytes of the <em>Driver Information</em> field of this + message.</p> + </td> + </tr> + + <tr> + <td><p>Driver Information</p></td> + <td><p>Driver information is stored in a format defined by the file driver.</p> + </td> + </tr> + </table> + </div> + +<br /> +<h4><a name="AinfoMessage">IV.A.2.v. The Attribute Info +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Attribute + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0015</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message stores information about the attributes on an + object, such as the maximum creation index for the attributes + created and the location of the attribute storage when the + attributes are stored “densely”.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Attribute Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Maximum Creation Index <em>(optional)</em></td> + </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Name v2 B-tree Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Creation Order v2 B-tree Address<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the attribute index information flag with the + following definition: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, creation order for attributes is tracked. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, creation order for attributes is indexed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>The is the maximum creation order index value for the + attributes on the object.</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td><p>This is the address of the fractal heap to store dense + attributes.</p> + </td> + </tr> + + <tr> + <td><p>Attribute Name v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index the + names of densely stored attributes.</p> + </td> + </tr> + + <tr> + <td><p>Attribute Creation Order v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index the + creation order of densely stored attributes.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + </table> + </div> + +<br /> +<h4><a name="RefCountMessage">IV.A.2.w. The Object Reference +Count Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object Reference + Count</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0016</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message stores the number of hard links (in groups or + objects) pointing to an object: in other words, its + <em>reference count</em>.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Object Reference Count + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Reference count</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td><p>The unsigned 32-bit integer is the reference count for the + object. This message is only present in “version 2” + (or later) object headers, and if not present those object + header versions, the reference count for the object is assumed + to be 1.</p> + </td> + </tr> + + </table> + </div> + +<br /> +<h4><a name="FsinfoMessage">IV.A.2.x. The File Space Info +Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> File Space + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0018</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td> + <b>Description:</b></td> + <td>This message stores the file space management strategy (see + description below) that the library uses in handling file space + request for the file. It also contains the free-space section + threshold used by the library’s free-space managers for + the file. If the strategy is 1, this message also contains the + addresses of the file’s free-space managers which track + free space for each type of file space allocation. There are + six basic types of file space allocation: superblock, B-tree, + raw data, global heap, local heap, and object header. See the + description of <a href="#FreeSpaceManager">Free-space + Manager</a> as well the description of allocation types in + <a href="#AppendixB">Appendix B</a>.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + File Space Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Strategy</td> + <td colspan="2">Threshold<sup>L</sup></td> + </tr> + <tr> + <td colspan="4">Super-block Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">B-tree Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Raw Data Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Global Heap Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Local Heap Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Object Header Free-space Manager Address<sup>O</sup></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are of the size + specified in “Size of Offsets” field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are of the size + specified in “Size of Lengths” field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>This is the version number of this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Strategy</p></td> + <td><p>This is the file space management strategy for the file. + There are four types of strategies: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>With this strategy, the HDF5 Library’s free-space managers track the + free space that results from the manipulation of HDF5 objects + in the HDF5 file. The free space information is saved when the + file is closed, and reloaded when the file is reopened. + <br /> + When space is needed for file metadata or raw data, + the HDF5 Library first requests space from the library’s free-space + managers. If the request is not satisfied, the library requests space + from the aggregators. If the request is still not satisfied, + the library requests space from the virtual file driver. + That is, the library will use all of the mechanisms for allocating + space. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>This is the HDF5 Library’s default file space management strategy. + With this strategy, the library’s free-space managers track the free space + that results from the manipulation of HDF5 objects in the HDF5 file. + The free space information is NOT saved when the file is closed and + the free space that exists upon file closing becomes unaccounted + space in the file. + <br /> + As with strategy #1, the library will try all of the mechanisms + for allocating space. When space is needed for file metadata or + raw data, the library first requests space from the free-space + managers. If the request is not satisfied, the library requests + space from the aggregators. If the request is still not satisfied, + the library requests space from the virtual file driver. + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>With this strategy, the HDF5 Library does not track free space that results + from the manipulation of HDF5 objects in the HDF5 file and + the free space becomes unaccounted space in the file. + <br /> + When space is needed for file metadata or raw data, + the library first requests space from the aggregators. + If the request is not satisfied, the library requests space from + the virtual file driver. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>With this strategy, the HDF5 Library does not track free space that results + from the manipulation of HDF5 objects in the HDF5 file and + the free space becomes unaccounted space in the file. + <br /> + When space is needed for file metadata or raw data, + the library requests space from the virtual file driver. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Threshold</p></td> + <td><p>This is the free-space section threshold. + The library’s free-space managers will track only + free-space sections with size greater than or equal to + <em>threshold</em>. The default is to track free-space + sections of all sizes.</p> + </td> + </tr> + <tr> + <td><p>Superblock Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_SUPER allocation type. + </p> + </td> + </tr> + + <tr> + <td><p>B-tree Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_BTREE allocation type. + </p> + </td> + </tr> + + <tr> + <td><p>Raw Data Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_DRAW allocation type. + </p> + </td> + </tr> + + <tr> + <td><p>Global Heap Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_GHEAP allocation type. + </p> + </td> + </tr> + + <tr> + <td><p>Local Heap Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_LHEAP allocation type. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_OHDR allocation type. + </p> + </td> + </tr> + </table> + </div> + <br /> + + +<br /> +<h3><a name="DataStorage"> +IV.B. Disk Format: Level 2B - Data Object Data Storage</a></h3> + +<p>The data for an object is stored separately from its header + information in the file and may not actually be located in the HDF5 file + itself if the header indicates that the data is stored externally. The + information for each record in the object is stored according to the + dimensionality of the object (indicated in the dataspace header message). + Multi-dimensional array data is stored in C order; in other words, the + “last” dimension changes fastest.</p> + +<p>Data whose elements are composed of atomic datatypes are stored in IEEE + format, unless they are specifically defined as being stored in a different + machine format with the architecture-type information from the datatype + header message. This means that each architecture will need to [potentially] + byte-swap data values into the internal representation for that particular + machine.</p> + +<p> Data with a variable-length datatype is stored in the global heap + of the HDF5 file. Global heap identifiers are stored in the + data object storage.</p> + +<p>Data whose elements are composed of reference datatypes are stored in + several different ways depending on the particular reference type involved. + Object pointers are just stored as the offset of the object header being + pointed to with the size of the pointer being the same number of bytes as + offsets in the file.</p> + +<p>Dataset region references are stored as a heap-ID which points to +the following information within the file-heap: an offset of the object +pointed to, number-type information (same format as header message), +dimensionality information (same format as header message), sub-set start +and end information (in other words, a coordinate location for each), +and field start and end names (in other words, a [pointer to the] string +indicating the first field included and a [pointer to the] string name +for the last field). </p> + +<p>Data of a compound datatype is stored as a contiguous stream of the items + in the structure, with each item formatted according to its datatype.</p> + + + +<br /> +<br /> +<hr /> +<h2><a name="AppendixA"> +V. Appendix A: Definitions</a></h2> + +<p>Definitions of various terms used in this document are included in +this section.</p> + + <div align="center"> + <table class="glossary"> + <tr> + <th width="20%">Term</th> + <th>Definition</th> + </tr> + + <tr> + <td>Undefined Address</td> + <td>The <a name="UndefinedAddress">undefined + address</a> for a file is a file address with all bits + set: in other words, <code>0xffff...ff</code>.</td> + </tr> + + <tr> + <td>Unlimited Size</td> + <td>The <a name="UnlimitedDim">unlimited size</a> + for a size is a value with all bits set: in other words, + <code>0xffff...ff</code>.</td> + </tr> + + </table> + </div> + + + +<br /> +<br /> +<hr /> +<h2><a name="AppendixB"> +VI. Appendix B: File Memory Allocation Types</a></h2> + +<p>There are six basic types of file memory allocation as follows: +</p> + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Description</th> + </tr> + + <tr> + <td>H5FD_MEM_SUPER</td> + <td>File memory allocated for <em>Superblock.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_BTREE</td> + <td>File memory allocated for <em>B-tree.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_DRAW</td> + <td>File memory allocated for raw data.</td> + </tr> + + <tr> + <td>H5FD_MEM_GHEAP</td> + <td>File memory allocated for <em>Global Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>File memory allocated for <em>Local Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>File memory allocated for <em>Object Header.</em></td> + </tr> + </table> + </div> + +<p>There are other file memory allocation types that are mapped to the +above six basic allocation types because they are similar in nature. +The mapping is listed in the following table: +</p> + + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Mapping of Allocation Types to Basic Allocation Types</th> + </tr> + + <tr> + <td>H5FD_MEM_SUPER</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_BTREE</td> + <td>H5FD_MEM_SOHM_INDEX</td> + </tr> + + <tr> + <td>H5FD_MEM_DRAW</td> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + </tr> + + <tr> + <td>H5FD_MEM_GHEAP</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>H5FD_MEM_FHEAP_DBLOCK, H5FD_MEM_FSPACE_SINFO</td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>H5FD_MEM_FHEAP_HDR, H5FD_MEM_FHEAP_IBLOCK, H5FD_MEM_FSPACE_HDR, H5FD_MEM_SOHM_TABLE</td> + </tr> + </table> + </div> + +<p>Allocation types that are mapped to basic allocation types are described below: +</p> + + <div align="center"> + <table class="desc"> + <tr> + <th width="30%">Allocation Type</th> + <th>Description</th> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HDR</td> + <td>File memory allocated for <em>Fractal Heap Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_DBLOCK</td> + <td>File memory allocated for <em>Fractal Heap Direct Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_IBLOCK</td> + <td>File memory allocated for <em>Fractal Heap Indirect Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + <td>File memory allocated for huge objects in the fractal heap.</td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_HDR</td> + <td>File memory allocated for <em>Free-space Manager Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_SINFO</td> + <td>File memory allocated for <em>Free-space Section List</em> of the free-space manager.</td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_TABLE</td> + <td>File memory allocated for <em>Shared Object Header Message Table.</em></td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_INDEX</td> + <td>File memory allocated for <em>Shared Message Record List.</em></td> + </tr> + </table> + </div> +</body> +</html> diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html new file mode 100644 index 0000000..e16805f --- /dev/null +++ b/doxygen/examples/H5.format.html @@ -0,0 +1,20400 @@ +<html> + <head> + <title> + HDF5 File Format Specification Version 3.0 + </title> + + <style> + h1 { display: block; + margin-top: 24px; + margin-bottom: 24px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + font-size: 300%; + } + + h2 { display: block; + margin-top: 60px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + border-style: solid; + border-top-style: medium; + border-top-color: #A9A9A9; + border-bottom: none; + border-left: none; + border-right: none; + font-size: 250%; + } + + h3 { display: block; + margin-top: 40px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + font-size: 200%; + } + + h4 { display: block; + margin-top: 32px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + font-size: 150%; + } + + p { display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; + font-size: 100%; + } + <!-- + p.item { margin-left: 2em; + text-indent: -2em + } --> + <!-- p.item2 { margin-left: 2em; text-indent: 2em} --> + + table.format { border:solid; + border-collapse:collapse; + caption-side:top; + text-align:center; + width:80%; + } + table.format th { border:ridge; + padding:4px; + width:25%; + } + table.format td { border:ridge; + padding:4px; + } + table.format caption { font-weight:bold; + font-size:larger; + } + + table.note {border:none; + text-align:right; + width:80%; + } + + table.desc { border:solid; + border-collapse:collapse; + caption-size:top; + text-align:left; + width:80%; + } + table.desc tr { vertical-align:top; + } + table.desc th { border-style:ridge; + font-size:larger; + padding:4px; + <!-- text-decoration:underline; --> + } + table.desc td { border-style:ridge; + <!-- padding: 4px; --> + vertical-align:text-top; + } + table.desc caption { font-weight:bold; + font-size:larger; + } + + table.list { border:none; + width:100% + } + table.list tr { vertical-align:text-top; + } + table.list th { border:none; + text-decoration:underline; + vertical-align:text-top; + } + table.list td { border:none; + vertical-align:text-top; + } + + table.msgdesc { border:none; + text-align:left; + width: 80% + } + table.msgdesc tr { vertical-align:text-top; + border-spacing:0; + padding:0; } + table.msgdesc th { border:none; + text-decoration:underline; + vertical-align:text-top; } + table.msgdesc td { border:none; + vertical-align:text-top; + } + + table.list80 { border:none; + width:80% + } + table.list80 tr { vertical-align:text-top; + } + table.list80 th { border:none; + text-decoration:underline; + vertical-align:text-top; + } + table.list80 td { border:none; + vertical-align:text-top; + } + + table.glossary { border:none; + text-align:left; + width: 80% + } + table.glossary tr { vertical-align:text-top; + border-spacing:0; + padding:0; } + table.glossary th { border:none; + text-align:left; + text-decoration:underline; + vertical-align:text-top; } + table.glossary td { border:none; + text-align:left; + vertical-align:text-top; + } + + div { page-break-inside:avoid; + page-break-after:auto + } + + </style> + + <!-- #BeginLibraryItem "/ed_libs/styles_Format.lbi" --> + <!-- + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * Copyright by the Board of Trustees of the University of Illinois. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the files COPYING and Copyright.html. COPYING can be found at the root * + * of the source code distribution tree; Copyright.html can be found at the * + * root level of an installed copy of the electronic HDF5 document set and * + * is linked from the top-level documents page. It can also be found at * + * http://www.hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * + * access to either file, you may request a copy from help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + --> + <!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/NavBar_ADevG.lbi" --> + </head> + <body> + <!-- #EndLibraryItem --> + + <center> + <table border="0" width="90%"> + <tr> + <td valign="top"> + <ol type="I"> + <li><a href="#Intro">Introduction</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ThisDocument">This Document</a></li> + <li><a href="#ChangesForHdf5_1_12">Changes for HDF5 1.12</a></li> + <li><a href="#ChangesForHdf5_1_10">Changes for HDF5 1.10</a></li> + </ol> + </font> + + <li><a href="#FileMetaData">Disk Format: Level 0 - File Metadata</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Superblock">Disk Format: Level 0A - Format Signature + and Superblock</a></li> + <li><a href="#DriverInfo">Disk Format: Level 0B - File Driver + Info</a></li> + <li><a href="#SuperblockExt">Disk Format: Level 0C - Superblock + Extension</a></li> + </ol> + </font> + <li><a href="#FileInfra">Disk Format: Level 1 - File Infrastructure</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Btrees">Disk Format: Level 1A - B-trees and B-tree + Nodes</a> + <ol type="1"> + <li><a href="#V1Btrees">Disk Format: Level 1A1 - Version 1 + B-trees</a></li> + <li><a href="#V2Btrees">Disk Format: Level 1A2 - Version 2 + B-trees</a></li> + </ol> + </li> + <li><a href="#SymbolTable">Disk Format: Level 1B - Group Symbol + Table Nodes</a></li> + <li><a href="#SymbolTableEntry">Disk Format: Level 1C - Symbol + Table Entry</a></li> + <li><a href="#LocalHeap">Disk Format: Level 1D - Local Heaps</a></li> + <li><a href="#GlobalHeap">Disk Format: Level 1E - Global Heap</a></li> + <li><a href="#GlobalHeapVDS">Disk Format: Level 1F - Global Heap + Block for Virtual Datasets</a></li> + <li><a href="#FractalHeap">Disk Format: Level 1G - Fractal Heap</a></li> + <li><a href="#FreeSpaceManager">Disk Format: Level 1H - Free-space + Manager</a></li> + <li><a href="#SOHMTable">Disk Format: Level 1I - Shared Object + Header Message Table</a></li> + </ol> + </font> + <li><a href="#DataObject">Disk Format: Level 2 - Data Objects</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object Headers</a></li> + <ol type="1"> + <li><a href="#ObjectHeaderPrefix">Disk Format: Level 2A1 - + Data Object Header Prefix</a> + <ol type="a"> + <li><a href="#V1ObjectHeaderPrefix">Version 1 Data + Object Header Prefix</a></li> + <li><a href="#V2ObjectHeaderPrefix">Version 2 Data + Object Header Prefix</a></li> + </ol> + </li> + <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - + Data Object Header Messages</a></li> + <ol type="a"> + <li><a href="#NILMessage">The NIL Message</a></li> <!-- 0x0000 --> + <li><a href="#DataspaceMessage">The Dataspace Message</a></li> <!-- 0x0001 --> + <li><a href="#LinkInfoMessage">The Link Info Message</a></li> <!-- 0x0002 --> + <li><a href="#DatatypeMessage">The Datatype Message</a></li> <!-- 0x0003 --> + <li><a href="#OldFillValueMessage">The Data Storage - + Fill Value (Old) Message</a></li> <!-- 0x0004 --> + </ol> + </ol> + </ol> + </font> + </ol> + </td> + + <td> </td> + + <td valign="top"> + <ol type="I" start="4"> + <li><a href="#DataObject">Disk Format: Level 2 - Data + Objects</a><font size="-1"><i> (Continued)</i></li> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object + Headers</a><i> (Continued)</i> + <ol type="1" start="2"> + <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - + Data Object Header Messages</a><i> (Continued)</i></li> + <ol type="a" start="6"> + <li><a href="#FillValueMessage">The Data Storage - + Fill Value Message</a></li> <!-- 0x0005 --> + <li><a href="#LinkMessage">The Link Message</a></li> <!-- 0x0006 --> + <li><a href="#ExternalFileListMessage">The Data Storage - + External Data Files Message</a></li> <!-- 0x0007 --> + <li><a href="#LayoutMessage">The Data Layout Message</a></li> <!-- 0x0008 --> + <li><a href="#BogusMessage">The Bogus Message</a></li> <!-- 0x0009 --> + <li><a href="#GroupInfoMessage">The Group Info + Message</a></li> <!-- 0x000a --> + <li><a href="#FilterMessage">The Data Storage - + Filter Pipeline Message</a></li> <!-- 0x000b --> + <li><a href="#AttributeMessage">The Attribute + Message</a></li> <!-- 0x000c --> + <li><a href="#CommentMessage">The Object Comment + Message</a></li> <!-- 0x000d --> + <li><a href="#OldModificationTimeMessage">The Object + Modification Time (Old) Message</a></li> <!-- 0x000e --> + <li><a href="#SOHMTableMessage">The Shared Message + Table Message</a></li> <!-- 0x000f --> + <li><a href="#ContinuationMessage">The Object Header + Continuation Message</a></li> <!-- 0x0010 --> + <li><a href="#SymbolTableMessage">The Symbol + Table Message</a></li> <!-- 0x0011 --> + <li><a href="#ModificationTimeMessage">The Object + Modification Time Message</a></li> <!-- 0x0012 --> + <li><a href="#BtreeKValuesMessage">The B-tree + ‘K’ Values Message</a></li> <!-- 0x0013 --> + <li><a href="#DrvInfoMessage">The Driver Info + Message</a></li> <!-- 0x0014 --> + <li><a href="#AinfoMessage">The Attribute Info + Message</a></li> <!-- 0x0015 --> + <li><a href="#RefCountMessage">The Object Reference + Count Message</a></li> <!-- 0x0016 --> + <li><a href="#FsinfoMessage">The File Space Info + Message</a></li> <!-- 0x0017 --> + </ol> + </ol> + </li> + <li><a href="#DataStorage">Disk Format: Level 2B - Data Object Data Storage</a></li> + </ol> + </font> + <li><a href="#AppendixA">Appendix A: Definitions</a></li> + <li><a href="#AppendixB">Appendix B: File Space Allocation + Types</a></li> + <li><a href="#AppendixC"> + Appendix C: Types of Indexes for Dataset Chunks</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#SingleChunk">The Single Chunk Index</a></li> + <li><a href="#Implicit">The Implicit Index</a></li> + <li><a href="#FixedArray">The Fixed Array Index</a></li> + <li><a href="#ExtensibleArray">The Extensible Array Index</a></li> + <li><a href="#AppendV2Btrees">The Version 2 B-trees Index</a></li> + </ol> + </font> + <li><a href="#AppendixD"> + Appendix D: Encoding for Dataspace and Reference</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#DataspaceEncode">Dataspace Encoding</a></li> + <li><a href="#ReferenceEncodeRV">Reference Encoding (Revised)</a></li> + <li><a href="#ReferenceEncodeDP">Reference Encoding (Backward Compatibility)</a></li> + </ol> + </font> + </ol> + </td></tr> + </table> + </center> + + + <a name="Intro"><h2>I. Introduction</h2></a> + + <table align="right" width="100"> + <tr><td> </td><td align="center"> + <hr /> + <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace="15" vspace="15"> + </td><td> </td></tr> + <tr><td> </td><td align="center"> + <strong>Figure 1:</strong> Relationships among the HDF5 root group, other groups, and objects + <hr /> + </td><td> </td></tr> + + <tr><td> </td><td align="center"> + <img src="FF-IH_FileObject.gif" alt="HDF5 Objects" hspace="15" vspace="15"> + </td><td> </td></tr> + <tr><td> </td><td align="center"> + <strong>Figure 2:</strong> HDF5 objects -- datasets, datatypes, or dataspaces + <hr /> + </td><td> </td></tr> + </table> + + + <p>The format of an HDF5 file on disk encompasses several + key ideas of the HDF4 and AIO file formats as well as + addressing some shortcomings therein. The new format is + more self-describing than the HDF4 format and is more + uniformly applied to data objects in the file.</p> + + <p>An HDF5 file appears to the user as a directed graph. + The nodes of this graph are the higher-level HDF5 objects + that are exposed by the HDF5 APIs:</p> + + <ul> + <li>Groups</li> + <li>Datasets</li> + <li>Committed (formerly Named) datatypes</li> + </ul> + + <p>At the lowest level, as information is actually written to the disk, + an HDF5 file is made up of the following objects:</p> + <ul> + <li>A superblock</li> + <li>B-tree nodes</li> + <li>Heap blocks</li> + <li>Object headers</li> + <li>Object data</li> + <li>Free space</li> + </ul> + + <p>The HDF5 Library uses these low-level objects to represent the + higher-level objects that are then presented to the user or + to applications through the APIs. For instance, a group is an + object header that contains a message that points to a local + heap (for storing the links to objects in the group) and to a + B-tree (which indexes the links). A dataset is an object header + that contains messages that describe the datatype, dataspace, + layout, filters, external files, fill value, and other elements + with the layout message pointing to either a raw data chunk or + to a B-tree that points to raw data chunks.</p> + + + <a name="ThisDocument"><h3>I.A. This Document</h3></a> + + <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> + + <p>Three levels of information comprise the file format. + Level 0 contains basic information for identifying and + defining information about the file. Level 1 information contains + the information about the pieces of a file shared by many objects + in the file (such as B-trees and heaps). Level 2 is the rest + of the file and contains all of the data objects with each object + partitioned into header information, also known as + <em>metadata</em>, and data.</p> + + <p>The various components of the lower-level data objects are + described in pairs of tables. The first table shows the format + layout, and the second table describes the fields. The titles + of format layout tables begin with “Layout”. The + titles of the tables where the fields are described begin with + “Fields”. For example, the table that describes the + format of the <a href="#V2Btrees">version 2 B-tree header</a> has + a title of “Layout: Version 2 B-tree Header”, and the + fields in the version 2 B-tree header are described in the table + titled “Fields: Version 2 B-tree Header”. + + <p>The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans + in the table. There are exceptions: </p> + <ul> + <li> The size may be overridden by specifying a size in + parentheses</li> + <li> The size of addresses is determined by the + <em><a href="#SizeOfOffsetsV0">Size of Offsets</a></em> field + in the superblock and is indicated in this document with a + superscripted ‘O’</li> + <li> The size of length fields is determined by the + <em><a href="#SizeOfLengthsV0">Size of Lengths</a></em> field in + the superblock and is indicated in this document with a + superscripted ‘L’</li> + </ul> + + <p>Values for all fields in this document should be treated as unsigned + integers, unless otherwise noted in the description of a field. + Additionally, all metadata fields are stored in little-endian byte + order. + </p> + + <p>All checksums used in the format are computed with the + <a href="http://www.burtleburtle.net/bob/hash/doobs.html">Jenkins’ + lookup3</a> algorithm. + </p> + + <p>Whenever a bit flag or field is mentioned for an entry, bits are + numbered from the lowest bit position in the entry. + </p> + + <p>Various format tables in this document have cells with + “This space inserted only to align table nicely”. These + entries in the table are just to make the table presentation nicer + and do not represent any values or padding in the file. + </p> + + <a name="ChangesForHdf5_1_12"> + <h3>I.B. Changes for HDF5 1.12</h3></a> + <p>The following sections have been + changed or added for the 1.12 release:</p> + <ul> + <li>Under <a href="#DatatypeMessage">“The Datatype Message”</a>, + in the Description for “Fields:Datatype Message”, + version 4 was added and Reference class (7) of the datatype was updated to describe version 4.</li> + <li><a href="#AppendixD"> + “Appendix D: Encoding for Dataspace and Reference”</a> + was added. </li> + </ul> + + + <a name="ChangesForHdf5_1_10"> + <h3>I.C. Changes for HDF5 1.10</h3></a> + + <p>The following sections have been + changed or added for the 1.10 release:</p> + <ul> + <li>In the <a href="#Superblock"> + “Disk Format: Level 0A - Format Signature and + Superblock”</a> section, version 3 of the superblock was + added. </li> + <li>In the <a href="#SuperblockExt"> + “Disk Format: Level 0C - Superblock Extension”</a> + section, a link to the Data Storage message was added. </li> + <li>In the <a href="#V2Btrees"> + “Disk Format: Level 1A2 - Version 2 B-trees”</a> + section, additional B-tree types were added. Tables that + describe the <a href="#V2BtreesType10">type 10</a> and + <a href="#V2BtreesType11">11</a> record layouts were added at + the end of the section.</li> + <li>The <a href="#GlobalHeapVDS">“Disk Format: Level 1F - + Global Heap Block for Virtual Datasets”</a> was added. + </li> + <li><a href="#LayoutMessage"> + “The Data Layout Message”</a> section was changed. + The name was changed, and <a href="#DataLayoutV4">version 4</a> + of the data layout message was added for the virtual type.</li> + <li>The <a href="#FsinfoMessage"> + “The File Space Info Message”</a> header message + type was added.</li> + <li><a href="#AppendixC"> + “Appendix C: Types of Indexes for Dataset Chunks”</a> + was added. Five indexing types were added.</li> + </ul> + + + + <h2><a name="FileMetaData"> + II. Disk Format: Level 0 - File Metadata</a></h2> + + + + <h3><a name="Superblock"> + II.A. Disk Format: Level 0A - Format Signature and Superblock</a></h3> + + <p>The superblock may begin at certain predefined offsets within + the HDF5 file, allowing a block of unspecified content for + users to place additional information at the beginning (and + end) of the HDF5 file without limiting the HDF5 Library’s + ability to manage the objects within the file itself. This + feature was designed to accommodate wrapping an HDF5 file in + another file format or adding descriptive information to an HDF5 + file without requiring the modification of the actual file’s + information. The superblock is located by searching for the + HDF5 format signature at byte offset 0, byte offset 512, and at + successive locations in the file, each a multiple of two of + the previous location; in other words, at these byte offsets: + 0, 512, 1024, 2048, and so on.</p> + + <p>The superblock is composed of the format signature, followed by a + superblock version number and information that is specific to each + version of the superblock. + + <p>Currently, there are four versions of the superblock format: + <ul> + <li>Version 0 is the default format.</li> + <li>Version 1 is the same as version 0 but with the + “<em>Indexed Storage Internal Node K</em>” field + for storing non-default B-tree ‘K’ value.</li> + <li>Version 2 has some fields eliminated and compressed from + superblock format versions 0 and 1. It has added checksum support + and superblock extension to store additional superblock + metadata.</li> + <li>Version 3 is the same as version 2 except that the field + “<em>File Consistency Flags</em>” is used for file + locking. This format version will enable support for the latest + version.</li> + </ul> + + <p>Versions 0 and 1 of the superblock are described below:</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Superblock (Versions 0 and 1) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Format Signature + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td>Version # of Superblock</td> + <td>Version # of File’s Free Space Storage</td> + <td>Version # of Root Group Symbol Table Entry</td> + <td>Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td>Version Number of Shared Header Message Format</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="2">Group Leaf Node K</td> + <td colspan="2">Group Internal Node K</td> + </tr> + + <tr> + <td colspan="4">File Consistency Flags</td> + </tr> + + <tr> + <td colspan="2" style="border:dotted;">Indexed Storage Internal Node K<sup>1</sup></td> + <td colspan="2" style="border:dotted;">Reserved + <em>(zero)</em><sup>1</sup></td> + </tr> + + <tr> + <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of File Free space Info<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Driver Information Block Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Root Group Symbol Table Entry</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with a ‘1’ in the above table are + new in version 1 of the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Superblock (Versions 0 and 1) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td><p>This field contains a constant value and can be used to + quickly identify a file as being an HDF5 file. The + constant value is designed to allow easy identification of + an HDF5 file and to allow certain types of data corruption + to be detected. The file signature of an HDF5 file always + contains the following values:</p> + <center> + <table border align="center" cellpadding="4"> + <tr align="center"> + <td align="right">Decimal:</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align="center"> + <td align="right">Hexadecimal:</td> + <td>89</td> + <td>48</td> + <td>44</td> + <td>46</td> + <td>0d</td> + <td>0a</td> + <td>1a</td> + <td>0a</td> + </tr> + + <tr align="center"> + <td align="right">ASCII C Notation:</td> + <td>\211</td> + <td>H</td> + <td>D</td> + <td>F</td> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + </table> + </center> + <p>This signature both identifies the file as an HDF5 file + and provides for immediate detection of common + file-transfer problems. The first two bytes distinguish + HDF5 files on systems that expect the first two bytes to + identify the file type uniquely. The first byte is + chosen as a non-ASCII value to reduce the probability + that a text file may be misrecognized as an HDF5 file; + also, it catches bad file transfers that clear bit + 7. Bytes two through four name the format. The CR-LF + sequence catches bad file transfers that alter newline + sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse + of the CR-LF translation problem. (This is a direct + descendent of the + <a href="http://www.libpng.org/pub/png/spec/iso/index-object.html#5PNG-file-signature">PNG</a> file + signature.)</p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p></td> + </tr> + + <tr> + <td><p>Version Number of the Superblock</p></td> + <td><p>This value is used to determine the format of the + information in the superblock. When the format of the + information in the superblock is changed, the version number + is incremented to the next integer and can be used to + determine how the information in the superblock is + formatted.</p> + + <p>Values of 0, 1 and 2 are defined for this field (the + format of version 2 is described below, not here). + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Version Number of the File’s Free Space + Information</p></td> + <td> + <p>This value is used to determine the format of the + file’s free space information. + </p> + <p>The only value currently valid in this field is ‘0’, which + indicates that the file’s free space is as described + <a href="#FreeSpaceManager">below</a>. + </p> + + <p><em>This field is present in versions 0 and 1 of the + superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Root Group Symbol Table + Entry</p></td> + <td><p>This value is used to determine the format of the + information in the Root Group Symbol Table Entry. When the + format of the information in that field is changed, the + version number is incremented to the next integer and can be + used to determine how the information in the field + is formatted.</p> + <p>The only value currently valid in this field is ‘0’, + which indicates that the root group symbol table entry is + formatted as described <a href="#SymbolTableEntry">below</a>.</p> + <p><em>This field is present in version 0 and 1 of the + superblock.</em></p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Shared Header Message Format</p></td> + <td><p>This value is used to determine the format of the + information in a shared object header message. Since the format + of the shared header messages differs from the other private + header messages, a version number is used to identify changes + in the format. + </p> + <p>The only value currently valid in this field is ‘0’, which + indicates that shared header messages are formatted as + described <a href="#ObjectHeaderMessages">below</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p><a name="SizeOfOffsetsV0">Size of Offsets</a></p></td> + <td><p>This value contains the number of bytes used to store + addresses in the file. The values for the addresses of + objects in the file are offsets relative to a base address, + usually the address of the superblock signature. This + allows a wrapper to be added after the file is created + without invalidating the internal offset locations. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p><a name="SizeOfLengthsV0">Size of Lengths</a></p></td> + <td><p>This value contains the number of bytes used to store + the size of an object. + </p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Group Leaf Node K</p></td> + <td> + <p>Each leaf node of a group B-tree will have at + least this many entries but not more than twice this + many. If a group has a single leaf node then it + may have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Group Internal Node K</p></td> + <td> + <p>Each internal node of a group B-tree will have at + least this many entries but not more than twice this + many. If the group has only one internal + node then it might have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>File Consistency Flags</p></td> + <td> + <p>This field is unused and should be ignored. + </p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td> + <p>Each internal node of an indexed storage B-tree will have at + least this many entries but not more than twice this + many. If the index storage B-tree has only one internal + node then it might have fewer entries. + </p> + <p>This value must be greater than zero. + </p> + <p>See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p><em>This field is present in version 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This is the absolute file address of the first byte of + the HDF5 data within the file. The library currently + constrains this value to be the absolute file address + of the superblock itself when creating new files; + future versions of the library may provide greater + flexibility. When opening an existing file and this address does + not match the offset of the superblock, the library assumes + that the entire contents of the HDF5 file have been adjusted in + the file and adjusts the base address and end of file address to + reflect their new positions in the file. Unless otherwise noted, + all other file addresses are relative to this base + address. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Address of Global Free-space Index</p></td> + <td> + <p>The file’s free space is not persistent for version 0 and 1 of + the superblock. + Currently this field always contains the + <a href="#UndefinedAddress">undefined address</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This is the absolute file address of the first byte past + the end of all HDF5 data. It is used to determine whether a + file has been accidently truncated and as an address where + file data allocation can occur if space from the free list is + not used. + </p> + + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Block Address</p></td> + <td> + <p>This is the relative file address of the file driver + information block which contains driver-specific + information needed to reopen the file. If there is no + driver information block then this entry should be the + <a href="#UndefinedAddress">undefined address</a>. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Root Group Symbol Table Entry</p></td> + <td> + <p>This is the <a href="#SymbolTableEntry">symbol table entry</a> + of the root group, which serves as the entry point into + the group graph for the file. + </p> + + <p><em>This field is present in version 0 and 1 of the superblock.</em> + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <br /> + <p>Versions 2 and 3 of the superblock are described below:</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: Superblock (Versions 2 and 3) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Format Signature + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td>Version # of Superblock</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>File Consistency Flags</td> + </tr> + + <tr> + <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Superblock Extension Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Root Group Object Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Superblock Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Superblock (Versions 2 and 3) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p></td> + </tr> + + <tr> + <td><p>Version Number of the Superblock</p></td> + <td> + <p>This field has a value of 2 and has the same meaning as for + versions 0 and 1. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Offsets</p></td> + <td> + <p>This field is the same as described for + <a href="#SizeOfOffsetsV0">versions 0 and 1</a> of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Lengths</p></td> + <td> + <p>This field is the same as described for + <a href="#SizeOfLengthsV0">versions 0 and 1</a> of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>File Consistency Flags</p></td> + + <td> + <p>For superblock version + 2: This field is unused and should be ignored.</p> + <p>For superblock version + 3: This value contains flags to ensure file consistency for + file locking. Currently, the following bit flags are defined: + <ul> + <li>Bit 0 if set indicates that the file has been opened for + write access.</li> + <li>Bit 1 is reserved for future use.</li> + <li>Bit 2 if set indicates that the file has been opened for + single-writer/multiple-reader (SWMR) write access.</li> + <li>Bits 3-7 are reserved for future use.</li> + </ul> + <p> + Bit 0 should be set as the first action when a file has been + opened for write access. Bit 2 should be set when a file + has been opened for SWMR write access. These two bits should + be cleared only as the final action when closing a file. + </p> + <p><em>This field is present in version 0+ of the superblock.</em> + </p> + <p><em>The size of this + field has been reduced from 4 bytes in superblock format + versions 0 and 1 to 1 byte.</em> + </p> + </td> + + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This field is the same as described for versions 0 and + 1 of the superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Superblock Extension Address</p></td> + <td> + <p>The field is the address of the object header for the + <a href="#SuperblockExt">superblock extension</a>. + If there is no extension then this entry should be the + <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of the + superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Root Group Object Header Address</p></td> + <td> + <p>This is the address of + the <a href="#DataObject">root group object header</a>, + which serves as the entry point into the group graph for the file. + </p> + </td> + </tr> + + <tr> + <td><p>Superblock Checksum</p></td> + <td> + <p>The checksum for the superblock. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + + <h3><a name="DriverInfo"> + II.B. Disk Format: Level 0B - File Driver Info</a></h3> + + <p>The <b>driver information block</b> is an optional region of the + file which contains information needed by the file driver + to reopen a file. The format is described below:</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Driver Information Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved</td> + </tr> + + <tr> + <td colspan="4">Driver Information Size</td> + </tr> + + <tr> + <td colspan="4"><br />Driver Identification + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Driver Information + <em>(variable size)</em><br /><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Driver Information Block + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number of the Driver Information Block. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td> + <p>The size in bytes of the <em>Driver Information</em> field. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td> + <p>This is an eight-byte ASCII string without null + termination which identifies the driver and/or version number + of the Driver Information Block. The predefined driver encoded + in this field by the HDF5 Library is identified by the + letters <code>NCSA</code> followed by the first four characters of + the driver name. If the Driver Information block is not + the original version then the last letter(s) of the + identification will be replaced by a version number in + ASCII, starting with 0. + </p> + <p> + Identification for user-defined drivers is also eight-byte long. + It can be arbitrary but should be unique to avoid + the four character prefix “NCSA”. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Driver Information</p></td> + <td>Driver information is stored in a format defined by the + file driver (see description below).</td> + </tr> + </table> + </div> + + <br /> + <p>The two drivers encoded in the <em>Driver Identification</em> + field are as follows:</p> + <ul> + <li> + Multi driver: + <p> + The identifier for this driver is “NCSAmulti”. + This driver provides a mechanism for segregating raw data and different types of metadata + into multiple files. + These files are viewed by the library as a single virtual HDF5 file with a single file address. + A maximum of 6 files will be created for the following data: + superblock, B-tree, raw data, global heap, local heap, and object header. + More than one type of data can be written to the same file. + </p></li> + <li> + Family driver + <p> + The identifier for this driver is “NCSAfami” and is encoded in this field for library version 1.8 and after. + This driver is designed for systems that do not support files larger than 2 gigabytes + by splitting the HDF5 file address space across several smaller files. + It does nothing to segregate metadata and raw data; + they are mixed in the address space just as they would be in a single contiguous file. + </p></li> + </ul> + <p>The format of the <em>Driver Information</em> field for the + above two drivers are described below:</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: Multi Driver Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Reserved</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File N<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File N<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 1 + <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 2 + <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File N + <em>(variable size)</em><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Multi Driver Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Member Mapping</p></td> + <td><p>These fields are integer values from 1 to 6 + indicating how the data can be mapped to or merged with another type of + data. + <table class="list"> + <tr> + <th width="20%" align="center">Member Mapping</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">1</td> + <td>The superblock data.</td> + </tr> + <tr> + <td align="center">2</td> + <td>The B-tree data.</td> + </tr> + <tr> + <td align="center">3</td> + <td>The raw data.</td> + </tr> + <tr> + <td align="center">4</td> + <td>The global heap data.</td> + </tr> + <tr> + <td align="center">5</td> + <td>The local heap data.</td> + </tr> + <tr> + <td align="center">6</td> + <td>The object header data.</td> + </tr> + </table></p> + <p>For example, if the third field has the value 3 and all the rest have the + value 1, it means there are two files: one for raw data, and one for superblock, + B-tree, global heap, local heap, and object header.</p> + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td><p>These fields are reserved and should always be zero.</p></td> + </tr> + + <tr> + <td><p>Address of Member File N</p></td> + <td><p>This field Specifies the virtual address at which the member file starts.</p> + <p>N is the number of member files.</p> + </td> + </tr> + + <tr> + <td><p>End of Address for Member File N</p></td> + <td><p>This field is the end of the allocated address for the member file. + </p></td> + </tr> + + <tr> + <td><p>Name of Member File N</p></td> + <td><p>This field is the null-terminated name of the member file and + its length should be multiples of 8 bytes. + Additional bytes will be padded with <em>NULL</em>s. The default naming + convention is <em>%s-X.h5</em>, where <em>X</em> is one of the letters + <em>s</em> (for superblock), <em>b</em> (for B-tree), <em>r</em> (for raw data), + <em>g</em> (for global heap), <em>l</em> (for local heap), and <em>o</em> (for + object header). The name of the whole HDF5 file will substitute the <em>%s</em> + in the string. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Family Driver Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="8"><br />Size of Member File<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Family Driver Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size of Member File</p></td> + <td><p>This field is the size of the member file in the family of files.</p></td> + </tr> + </table> + </div> + + <h3><a name="SuperblockExt"> + II.C. Disk Format: Level 0C - Superblock Extension</a></h3> + + <p>The <em>superblock extension</em> is used to store superblock metadata + which is either optional, or added after the version of the superblock + was defined. Superblock extensions may only exist when version 2 + or later of the superblock is used. A superblock extension is an object + header which may hold the following messages:</p> + <ul> + <li> + <a href="#SOHMTableMessage">Shared Message Table message</a> containing + information to locate the master table of shared object header message + indices.</li> + <li> + <a href="#BtreeKValuesMessage">B-tree ‘K’ Values message</a> containing + non-default B-tree ‘K’ values.</li> + <li> + <a href="#DrvInfoMessage">Driver Info message</a> containing information + needed by the file driver in order to reopen a file. + See also the + <a href="#DriverInfo">“Disk Format: Level 0B - File Driver + Info”</a> section above.</li> + <li> + <a href="#FsinfoMessage">File Space Info message</a> containing + information about file space handling in the file.</li> + </ul> + + + + <h2><a name="FileInfra"> + III. Disk Format: Level 1 - File Infrastructure</a></h2> + + <h3><a name="Btrees"> + III.A. Disk Format: Level 1A - B-trees and B-tree Nodes</a></h3> + + <p>B-trees allow flexible storage for objects which tend to grow + in ways that cause the object to be stored discontiguously. B-trees + are described in various algorithms books including “Introduction to + Algorithms” by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. B-trees are used in several places in the HDF5 file format, + when an index is needed for another data structure.</p> + + <p>The version 1 B-tree structure described below is the original + index structure. The version 1 B-trees are being phased out in + favor of the version 2 B-trees described below. Note that both + types of structures may be found in the same file depending on + the application settings when creating the file.</p> + + <h4><a name="V1Btrees"> + III.A.1. Disk Format: Level 1A1 - Version 1 B-trees</a></h4> + + <p>Version 1 B-trees in HDF5 files are an implementation of the + B-link tree. The sibling nodes at a particular level in + the tree are stored in a doubly-linked list. See the + “Efficient Locking for Concurrent Operations on B-trees” + paper by Phillip Lehman and S. Bing Yao as published in the + <cite>ACM Transactions on Database Systems</cite>, Vol. 6, No. 4, + December 1981.</p> + + <p>The B-trees implemented by the file format contain one more + key than the number of children. In other words, each child + pointer out of a B-tree node has a left key and a right key. + The pointers out of internal nodes point to sub-trees while + the pointers out of leaf nodes point to symbol nodes and + raw data chunks. + Aside from that difference, internal nodes and leaf nodes + are identical.</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: B-tree Nodes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Node Type</td> + <td>Node Level</td> + <td colspan="2">Entries Used</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Left Sibling<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Right Sibling<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 1<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 2 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 2<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Key 2<em>K</em> <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Child 2<em>K</em><sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Key 2<em>K</em>+1 + <em>(variable size)</em></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: B-tree Nodes + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>TREE</code>” + is used to indicate the beginning of a B-tree node. This + gives file consistency checking utilities a better chance + of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Node Type</p></td> + <td> + <p>Each B-tree points to a particular type of data. + This field indicates the type of data as well as + implying the maximum degree <em>K</em> of the tree and + the size of each Key field. + + + <table class="list"> + <tr> + <th width="20%" align="center">Node Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>This tree points to group nodes.</td> + </tr> + <tr> + <td align="center">1</td> + <td>This tree points to raw data chunk nodes.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Node Level</p></td> + <td> + <p>The node level indicates the level at which this node + appears in the tree (leaf nodes are at level zero). Not + only does the level indicate whether child pointers + point to sub-trees or to data, but it can also be used + to help file consistency checking utilities reconstruct + damaged trees. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Entries Used</p></td> + <td> + <p>This determines the number of children to which this + node points. All nodes of a particular type of tree + have the same maximum degree, but most nodes will point + to less than that number of children. The valid child + pointers and keys appear at the beginning of the node + and the unused pointers and keys appear at the end of + the node. The unused pointers and keys have undefined + values. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Address of Left Sibling</p></td> + <td> + <p>This is the relative file address of the left sibling of + the current node. If the current + node is the left-most node at this level then this field + is the <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Address of Right Sibling</p></td> + <td> + <p>This is the relative file address of the right sibling of + the current node. If the current + node is the right-most node at this level then this + field is the <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Keys and Child Pointers</p></td> + <td> + <p>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> + child pointers interleaved between the keys. The number + of keys and child pointers actually containing valid + values is determined by the node’s <em>Entries + Used</em> field. If that field is <em>N</em>, then the + B-tree contains <em>N</em> child pointers and + <em>N</em>+1 keys. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Key</p></td> + <td> + <p>The format and size of the key values is determined by + the type of data to which this tree points. The keys are + ordered and are boundaries for the contents of the child + pointer; that is, the key values represented by child + <em>N</em> fall between Key <em>N</em> and Key + <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the + tree points. + </p> + + <p> + The format of the key depends on the node type. + For nodes of node type 0 (group nodes), the key is formatted as + follows: + + <table class="list"> + <tr> + <td width="20%">A single field of + <i><a href="#SizeOfLengthsV0">Size of Lengths</a></i> + bytes:</td> + <td width="80%">Indicates the byte offset into the local heap + for the first object name in the subtree which + that key describes. + </td> + </tr> + </table> + </p> + + + <p> + For nodes of node type 1 (chunked raw data nodes), the key is + formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-4:</td> + <td width="80%">Size of chunk in bytes.</td> + </tr> + <tr> + <td>Bytes 4-8:</td> + <td>Filter mask, a 32-bit bit field indicating which + filters have been skipped for this chunk. Each filter + has an index number in the pipeline (starting at 0, with + the first filter to apply) and if that filter is skipped, + the bit corresponding to its index is set.</td> + </tr> + <tr> + <td>(<em>D + 1</em>) 64-bit fields:</td> + <td>The offset of the + chunk within the dataset where <i>D</i> is the number + of dimensions of the dataset, and the last value is the + offset within the dataset’s datatype and should + always be zero. For example, if + a chunk in a 3-dimensional dataset begins at the + position <code>[5,5,5]</code>, there will be three + such 64-bit values, each with the value of + <code>5</code>, followed by a <code>0</code> value.</td> + </tr> + </table> + </p> + + </td> + </tr> + + <tr valign="top"> + <td><p>Child Pointer</p></td> + <td> + <p>The tree node contains file addresses of subtrees or + data depending on the node level. Nodes at Level 0 point + to data addresses, either raw data chunks or group nodes. + Nodes at non-zero levels point to other nodes of the + same B-tree. + </p> + <p>For raw data chunk nodes, the child pointer is the address + of a single raw data chunk. For group nodes, the child pointer + points to a <a href="#SymbolTable">symbol table</a>, which contains + information for multiple symbol table entries. + </p> + </td> + </tr> + </table> + </div> + + <p> + Conceptually, each B-tree node looks like this:</p> + <center> + <table> + <tr valign="top" align="center"> + <td>key[0]</td><td> </td> + <td>child[0]</td><td> </td> + <td>key[1]</td><td> </td> + <td>child[1]</td><td> </td> + <td>key[2]</td><td> </td> + <td>...</td><td> </td> + <td>...</td><td> </td> + <td>key[<i>N</i>-1]</td><td> </td> + <td>child[<i>N</i>-1]</td><td> </td> + <td>key[<i>N</i>]</td> + </tr> + </table> + </center> + <br /> + + where child[<i>i</i>] is a pointer to a sub-tree (at a level + above Level 0) or to data (at Level 0). + Each key[<i>i</i>] describes an <i>item</i> stored by the B-tree + (a chunk or an object of a group node). The range of values + represented by child[<i>i</i>] is indicated by key[<i>i</i>] + and key[<i>i</i>+1]. + + + <p>The following question must next be answered: + “Is the value described by key[<i>i</i>] contained in + child[<i>i</i>-1] or in child[<i>i</i>]?” + The answer depends on the type of tree. + In trees for groups (node type 0), the object described by + key[<i>i</i>] is the greatest object contained in + child[<i>i</i>-1] while in chunk trees (node type 1) the + chunk described by key[<i>i</i>] is the least chunk in + child[<i>i</i>].</p> + + <p>That means that key[0] for group trees is sometimes unused; + it points to offset zero in the heap, which is always the + empty string and compares as “less-than” any valid + object name.</p> + + <p>And key[<i>N</i>] for chunk trees is sometimes unused; + it contains a chunk offset which compares as “greater-than” + any other chunk offset and has a chunk byte size of zero + to indicate that it is not actually allocated.</p> + + <h4><a name="V2Btrees"> + III.A.2. Disk Format: Level 1A2 - Version 2 B-trees</a></h4> + + <p>Version 2 (v2) B-trees are “traditional” B-trees + with one major difference. Instead of just using a simple pointer + (or address in the file) to a child of an internal node, the pointer + to the child node contains two additional pieces of information: + the number of records in the child node itself, and the total number + of records in the child node and all its descendants. Storing this + additional information allows fast array-like indexing to locate + the n<sup>th</sup> record in the B-tree.</p> + + <p>The entry into a version 2 B-tree is a header which contains global + information about the structure of the B-tree. The <em>root node + address</em> + field in the header points to the B-tree root node, which is either an + internal or leaf node, depending on the value in the header’s + <em>depth</em> field. An internal node consists of records plus + pointers to further leaf or internal nodes in the tree. A leaf node + consists of solely of records. The format of the records depends on + the B-tree type (stored in the header).</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Node Size</td> + </tr> + <tr> + <td colspan="2">Record Size</td> + <td colspan="2">Depth</td> + </tr> + <tr> + <td>Split Percent</td> + <td>Merge Percent</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Root Node Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="2">Number of Records in Root Node</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records in B-tree<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree Header + </caption> + + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTHD</code>” + is used to indicate the header of a version 2 (v2) B-tree + node. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree header. This document + describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of B-tree: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>This B-tree is used for testing only. This + value should <em>not</em> be used for storing + records in actual HDF5 files. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>This B-tree is used for indexing indirectly accessed, + non-filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">2</td> + <td>This B-tree is used for indexing indirectly accessed, + filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">3</td> + <td>This B-tree is used for indexing directly accessed, + non-filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">4</td> + <td>This B-tree is used for indexing directly accessed, + filtered ‘huge’ fractal heap objects. + </td> + </tr> + <tr> + <td align="center">5</td> + <td>This B-tree is used for indexing the ‘name’ field for + links in indexed groups. + </td> + </tr> + <tr> + <td align="center">6</td> + <td>This B-tree is used for indexing the ‘creation order’ + field for links in indexed groups. + </td> + </tr> + <tr> + <td align="center">7</td> + <td>This B-tree is used for indexing shared object header + messages. + </td> + </tr> + <tr> + <td align="center">8</td> + <td>This B-tree is used for indexing the ‘name’ field for + indexed attributes. + </td> + </tr> + <tr> + <td align="center">9</td> + <td>This B-tree is used for indexing the ‘creation order’ + field for indexed attributes. + </td> + </tr> + + <tr> + <td align="center">10</td> + <td>This B-tree is used for indexing chunks of + datasets with no filters and with more than one + dimension of unlimited extent. + </td> + </tr> + + <tr> + <td align="center">11</td> + <td>This B-tree is used for indexing chunks of + datasets with filters and more than one dimension + of unlimited extent. + </td> + </tr> + </table></p> + <p>The format of records for each type is described below.</p> + </td> + </tr> + + <tr valign="top"> + <td><p>Node Size</p></td> + <td> + <p>This is the size in bytes of all B-tree nodes. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Record Size</p></td> + <td> + <p>This field is the size in bytes of the B-tree record. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Depth</p></td> + <td> + <p>This is the depth of the B-tree. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Split Percent</p></td> + <td> + <p>The percent full that a node needs to increase above before it + is split. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Merge Percent</p></td> + <td> + <p>The percent full that a node needs to be decrease below before it + is split. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Root Node Address</p></td> + <td> + <p>This is the address of the root B-tree node. A B-tree with + no records will have the <a href="#UndefinedAddress">undefined + address</a> in this field. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Number of Records in Root Node</p></td> + <td> + <p>This is the number of records in the root node. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Total Number of Records in B-tree</p></td> + <td> + <p>This is the total number of records in the entire B-tree. + </p> + </td> + </tr> + + <tr valign="top"> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the B-tree header. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree Internal Node + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Records 0, 1, 2...N-1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer 0<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Number of Records N<sub>0</sub> for Child + Node 0 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node 0 + <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer 1<sup>O</sup><br /><br /></td> + </tr> + <td colspan="4"><br />Number of Records N<sub>1</sub> for + Child Node 1 <em>(variable size)</em></td> +</tr> +<tr> + <td colspan="4"><br />Total Number of Records for Child Node 1 + <em>(optional, variable size)</em></td> +</tr> +<tr> + <td colspan="4">...</td> +</tr> +<tr> + <td colspan="4"><br />Child Node Pointer N<sup>O</sup><br /><br /></td> +</tr> +<tr> + <td colspan="4"><br />Number of Records N<sub>n</sub> for + Child Node N <em>(variable size)</em></td> +</tr> +<tr> + <td colspan="4"><br />Total Number of Records for Child Node N + <em>(optional, variable size)</em></td> +</tr> +<tr> + <td colspan="4">Checksum</td> +</tr> +</table> + +<table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> +</table> +</div> + + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree Internal Node + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTIN</code>” is + used to indicate the internal node of a B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree internal node. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header. + </p> + </td> + </tr> + + <tr> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format + of records depends on the type of B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Child Node Pointer</p></td> + <td> + <p>This field is the address of the child node pointed to by the + internal node. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Records in Child Node</p></td> + <td> + <p>This is the number of records in the child node pointed to by + the corresponding <em>Node Pointer</em>. + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node. + </p> + <p> + The maximum number of records in a child node is computed + in the following way: + + <ul> + <li>Subtract the fixed size overhead for + the child node (for example, its signature, version, + checksum, and so on and <em>one</em> pointer triplet + of information for the child node (because there is one + more pointer triplet than records in each internal node)) + from the size of nodes for the B-tree. </li> + <li>Divide that result by the size of a record plus the + pointer triplet of information stored to reach each + child node from this node.</li> + </ul> + + </p> + <p> + Note that leaf nodes do not encode any + child pointer triplets, so the maximum number of records in a + leaf node is just the node size minus the leaf node overhead, + divided by the record size. + </p> + <p> + Also note that the first level of internal nodes above the + leaf nodes do not encode the <em>Total Number of Records in Child + Node</em> value in the child pointer triplets (since it is the + same as the <em>Number of Records in Child Node</em>), so the + maximum number of records in these nodes is computed with the + equation above, but using (<em>Child Pointer</em>, <em>Number of + Records in Child Node</em>) pairs instead of triplets. + </p> + <p> + The number of + bytes used to encode this field is the least number of bytes + required to encode the maximum number of records in a child + node value for the child nodes below this level + in the B-tree. + </p> + <p> + For example, if the maximum number of child records is + 123, one byte will be used to encode these values in this + node; if the maximum number of child records is + 20000, two bytes will be used to encode these values in this + node; and so on. The maximum number of bytes used to + encode these values is 8 (in other words, an unsigned + 64-bit integer). + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Records in Child Node</p></td> + <td> + <p>This is the total number of records for the node pointed to by + the corresponding <em>Node Pointer</em> and all its children. + This field exists only in nodes whose depth in the B-tree node + is greater than 1 (in other words, the “twig” + internal nodes, just above leaf nodes, do not store this + field in their child node pointers). + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node and its descendants. + </p> + <p> + The maximum possible number of records able to be stored in a + child node and its descendants is computed iteratively, in the + following way: The maximum number of records in a leaf node + is computed, then that value is used to compute the maximum + possible number of records in the first level of internal nodes + above the leaf nodes. Multiplying these two values together + determines the maximum possible number of records in child node + pointers for the level of nodes two levels above leaf nodes. + This process is continued up to any level in the B-tree. + </p> + <p> + The number of bytes used to encode this value is computed in + the same way as for the <em>Number of Records in Child Node</em> + field. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree Leaf Node + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Record 0, 1, 2...N-1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree Leaf Node + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>BTLF</code>“ + is used to indicate the leaf node of a version 2 (v2) B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree leaf node. + This document describes version 0. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header. + </p> + </td> + </tr> + + <tr> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format + of records depends on the type of B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<p>The record layout for each stored (in other words, non-testing) + B-tree type is as follows:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 1 Record Layout - Indirectly + Accessed, Non-filtered, ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 1 Record Layout - Indirectly + Accessed, Non-filtered, ‘Huge’ Fractal Heap Objects + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 2 Record Layout - Indirectly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask</td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 2 Record Layout - Indirectly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped for + this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that + filter is skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 3 Record Layout - Directly + Accessed, Non-filtered, ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 3 Record Layout - Directly + Accessed, Non-filtered, ‘Huge’ Fractal Heap Objects + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 4 Record Layout - Directly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask</td> + </tr> + <tr> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 4 Record Layout - Directly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped for + this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that + filter is skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + <tr> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 5 Record Layout - Link Name + for Indexed Group + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Hash of Name</td> + </tr> + <tr> + <td colspan="4">ID <em>(bytes 1-4)</em></td> + </tr> + + <tr> + <td colspan="3">ID <em>(bytes 5-7)</em></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 5 Record Layout - Link Name + for Indexed Group + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the link. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the link’s name. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 6 Record Layout - Creation + Order for Indexed Group + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Creation Order + <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">ID <em>(bytes 1-4)</em></td> + </tr> + <tr> + <td colspan="3">ID <em>(bytes 5-7)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 6 Record Layout - Creation + Order for Indexed Group + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the link. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-type 0 - Message in Heap) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Hash</td> + </tr> + <tr> + <td colspan="4">Reference Count</td> + </tr> + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-type 0 - Message in Heap) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is stored: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>The number of objects which reference this message.</p> + </td> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + shared message in the shared message index’s fractal heap.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-type 1 - Message in Object Header) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Hash</td> + </tr> + <tr> + <td>Reserved (zero)</td> + <td>Message Type</td> + <td colspan="2">Object Header Index</td> + </tr> + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-type 1 - Message in Object Header) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is stored: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Message Type</p></td> + <td> + <p>The object header message type of the shared message.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Index</p></td> + <td> + <p>This field indicates that the shared message is the n<sup>th</sup> message + of its type in the specified object header.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>The address of the object header containing the shared message.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 8 Record Layout - Attribute + Name for Indexed Attributes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Creation Order</td> + </tr> + <tr> + <td colspan="4">Hash of Name</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 8 Record Layout - Attribute + Name for Indexed Attributes + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + attribute in the object’s attribute fractal heap.</p> + </td> + </tr> + + <tr> + <td><p>Message Flags</p></td> + <td><p>The object header message flags for the attribute message.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute. + </p> + </td> + </tr> + + <tr> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the attribute. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the attribute’s name. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree, Type 9 Record Layout - Creation + Order for Indexed Attributes + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + </tr> + <tr> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"> + <em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Creation Order</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 9 Record Layout - Creation + Order for Indexed Attributes + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for the + attribute in the object’s attribute fractal heap.</p> + </td> + </tr> + + <tr> + <td><p>Message Flags</p></td> + <td> + <p>The object header message flags for the attribute message.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<a name="V2BtType10"></a> + <div align="center"> + <table class="format"> + <caption> + <a name="V2BtreesType10"></a> + Layout: Version 2 B-tree, Type 10 Record Layout - + Non-filtered Dataset Chunks + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dimension 0 Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dimension 1 Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #n Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 10 Record Layout - + Non-filtered Dataset Chunks +</caption> +<tr> + <th width="30%">Field Name</th> + <th>Description</th> +</tr> + +<tr> + <td><p>Address</p></td> + <td> + <p>This field is the address of the dataset chunk in the file.</p> + </td> +</tr> + +<tr> + <td><p>Dimension #n Scaled Offset</p></td> + <td> + <p>This field is the scaled offset of the chunk within the + dataset. <em>n</em> is the number of dimensions for the + dataset. The first scaled offset stored in the list is for + the slowest changing dimension, and the last scaled offset + stored is for the fastest changing dimension. Scaled offset + is calculated by dividing the chunk dimension sizes into + the chunk offsets.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + <a name="V2BtreesType11"></a> + Layout: Version 2 B-tree, Type 11 Record Layout - Filtered + Dataset Chunks + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Chunk Size + <em>(variable size; at most 8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filter Mask</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension 0 Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dimension 1 Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #n Scaled Offset + <em>(8 bytes)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree, Type 11 Record Layout - Filtered + Dataset Chunks +</caption> +<tr> + <th width="30%">Field Name</th> + <th>Description</th> +</tr> + +<tr> + <td><p>Address</p></td> + <td> + <p>This field is the address of the dataset chunk in the file.</p> + </td> +</tr> + +<tr> + <td><p>Chunk Size</p></td> + <td> + <p>This field is the size of the dataset chunk in bytes.</p> + </td> +</tr> + +<tr> + <td><p>Filter Mask</p></td> + <td> + <p>This field is the filter mask which indicates the filter + to skip for the dataset chunk. Each filter has an index + number in the pipeline and if that filter is skipped, + the bit corresponding to its index is set.</p> + </td> +</tr> + +<tr> + <td><p>Dimension #n Scaled Offset</p></td> + <td> + <p>This field is the scaled offset of the chunk within + the dataset. <em>n</em> is the number of dimensions for + the dataset. The first scaled offset stored in the list + is for the slowest changing dimension, and the last scaled + offset stored is for the fastest changing dimension.</p> + </td> +</tr> + +</table> +</div> + +<h3><a name="SymbolTable"> + III.B. Disk Format: Level 1B - Group Symbol Table Nodes</a></h3> + +<p>A group is an object internal to the file that allows + arbitrary nesting of objects within the file (including other + groups). A group maps a set of link names in the group to a set + of relative file addresses of objects in the file. Certain metadata + for an object to which the group points can be cached in the + group’s symbol table entry in addition to being in the + object’s header.</p> + +<p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each + component as a link in a group. The link for a + non-ultimate component points to the group containing + the next component. The link for the last + component points to the object being named.</p> + +<p>One implementation of a group is a collection of symbol table + nodes indexed by a B-tree. Each symbol table node contains entries + for one or more links. If an attempt is made to add a link to an + already full symbol table node containing 2<em>K</em> entries, then + the node is split and one node contains <em>K</em> symbols and the + other contains <em>K</em>+1 symbols.</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Symbol Table Node (A Leaf of a B-tree) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version Number</td> + <td>Reserved <em>(zero)</em></td> + <td colspan="2">Number of Symbols</td> + </tr> + + <tr> + <td colspan="4"><br /><br />Group Entries<br /><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Symbol Table Node (A Leaf of a B-tree) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SNOD</code>” is + used to indicate the + beginning of a symbol table node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version Number</p></td> + <td> + <p>The version number for the symbol table node. This + document describes version 1. (There is no version ‘0’ + of the symbol table node) + </p> + </td> + </tr> + + <tr> + <td><p>Number of Entries</p></td> + <td> + <p>Although all symbol table nodes have the same length, + most contain fewer than the maximum possible number of + link entries. This field indicates how many entries + contain valid data. The valid entries are packed at the + beginning of the symbol table node while the remaining + entries contain undefined values. + </p> + </td> + </tr> + + <tr> + <td><p>Symbol Table Entries</p></td> + <td> + <p>Each link has an entry in the symbol table node. + The format of the entry is described below. + There are 2<em>K</em> entries in each group node, where + <em>K</em> is the “Group Leaf Node K” value from the + <a href="#Superblock">superblock</a>. + </p> + </td> + </tr> + </table> +</div> + +<h3><a name="SymbolTableEntry"> + III.C. Disk Format: Level 1C - Symbol Table Entry </a></h3> + +<p>Each symbol table entry in a symbol table node is designed + to allow for very fast browsing of stored objects. + Toward that design goal, the symbol table entries + include space for caching certain constant metadata from the + object header.</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Symbol Table Entry + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Link Name Offset<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Cache Type</td> + </tr> + + <tr> + <td colspan="4">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Scratch-pad Space + <em>(16 bytes)</em><br /><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Symbol Table Entry + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Link Name Offset</p></td> + <td> + <p>This is the byte offset into the group’s local + heap for the name of the link. The name is null + terminated. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>Every object has an object header which serves as a + permanent location for the object’s metadata. In addition + to appearing in the object header, some of the object’s metadata + can be cached in the scratch-pad space. + </p> + </td> + </tr> + + <tr> + <td><p>Cache Type</p></td> + <td> + <p>The cache type is determined from the object header. + It also determines the format for the scratch-pad space: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>No data is cached by the group entry. This + is guaranteed to be the case when an object header + has a link count greater than one. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Group object header metadata is cached in the + scratch-pad space. This implies that the symbol table + entry refers to another group. + </td> + </tr> + <tr> + <td align="center">2</td> + <td>The entry is a symbolic link. The first four bytes + of the scratch-pad space are the offset into the local + heap for the link value. The object header address + will be undefined. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td> + <p>These four bytes are present so that the scratch-pad + space is aligned on an eight-byte boundary. They are + always set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Scratch-pad Space</p></td> + <td> + <p>This space is used for different purposes, depending + on the value of the Cache Type field. Any metadata + about an object represented in the scratch-pad + space is duplicated in the object header for that + object. + </p> + <p> + Furthermore, no data is cached in the group + entry scratch-pad space if the object header for + the object has a link count greater than one. + </p> + </td> + </tr> + </table> +</div> + +<h4>Format of the Scratch-pad Space</h4> + +<p>The symbol table entry scratch-pad space is formatted + according to the value in the Cache Type field.</p> + +<p>If the Cache Type field contains the value zero + <code>(0)</code> then no information is + stored in the scratch-pad space.</p> + +<p>If the Cache Type field contains the value one + <code>(1)</code>, then the scratch-pad space + contains cached metadata for another object header + in the following format:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Object Header Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address of B-tree<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Name Heap<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Object Header Scratch-pad Format + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address of B-tree</p></td> + <td> + <p>This is the file address for the root of the + group’s B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Name Heap</p></td> + <td> + <p>This is the file address for the group’s local + heap, in which are stored the group’s symbol names. + </p> + </td> + </tr> + </table> +</div> + + +<br /> +<br /> +<br /> +<p>If the Cache Type field contains the value two + <code>(2)</code>, then the scratch-pad space + contains cached metadata for a symbolic link + in the following format:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Symbolic Link Scratch-pad Format + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Offset to Link Value</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Symbolic Link Scratch-pad Format + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Offset to Link Value</p></td> + <td> + <p>The value of a symbolic link (that is, the name of the + thing to which it points) is stored in the local heap. + This field is the 4-byte offset into the local heap for + the start of the link value, which is null terminated. + </p> + </td> + </tr> + </table> +</div> + +<h3><a name="LocalHeap"> + III.D. Disk Format: Level 1D - Local Heaps</a></h3> + +<p>A local heap is a collection of small pieces of data that are particular + to a single object in the HDF5 file. Objects can be + inserted and removed from the heap at any time. + The address of a heap does not change once the heap is created. + For example, a group stores addresses of objects in symbol table nodes + with the names of links stored in the group’s local heap. +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Local Heap + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Data Segment Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset to Head of Free-list<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Data Segment<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Local Heap + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>HEAP</code>” + is used to indicate the + beginning of a heap. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>Each local heap has its own version number so that new + heaps can be added to old files. This document + describes version zero (0) of the local heap. + </p> + </td> + </tr> + + <tr> + <td><p>Data Segment Size</p></td> + <td> + <p>The total amount of disk memory allocated for the heap + data. This may be larger than the amount of space + required by the objects stored in the heap. The extra + unused space in the heap holds a linked list of free blocks. + </p> + </td> + </tr> + + <tr> + <td><p>Offset to Head of Free-list</p></td> + <td> + <p>This is the offset within the heap data segment of the + first free block (or the + <a href="#UndefinedAddress">undefined address</a> if there is no + free block). The free block contains + <a href="#SizeOfLengthsV0">Size of Lengths</a> bytes that + are the offset of the next free block (or the + value ‘1’ if this is the + last free block) followed by Size of Lengths bytes that store + the size of this free block. The size of the free block includes + the space used to store the offset of the next free block and + the size of the current block, making the minimum size of a free + block 2 * Size of Lengths. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Data Segment</p></td> + <td> + <p>The data segment originally starts immediately after + the heap header, but if the data segment must grow as a + result of adding more objects, then the data segment may + be relocated, in its entirety, to another part of the + file. + </p> + </td> + </tr> + </table> +</div> + +<p>Objects within a local heap should be aligned on an 8-byte boundary.</p> + +<h3><a name="GlobalHeap"> + III.E. Disk Format: Level 1E - Global Heap</a></h3> + +<p>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The + global heap was designed to satisfy these goals:</p> + +<ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap + objects will typically be shared among several datasets, it is + probable that the object will be accessed repeatedly.</li> + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of + object references will have a global heap object for each + reference. Reading the entire set of object references + should result in a few large I/O requests instead of one small + I/O request for each reference.</li> + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed + for other uses.</li> +</ol> + + +<p>The implementation of the heap makes use of the memory management + already available at the file level and combines that with a new + object called a <em>collection</em> to achieve goal B. The global heap + is the set of all collections. Each global heap object belongs to + exactly one collection, and each collection contains one or more global + heap objects. For the purposes of disk I/O and caching, a collection is + treated as an atomic object, addressing goal A. +</p> + +<p>When a global heap object is deleted from a collection (which + occurs when its reference count falls to zero), objects located + after the deleted object in the collection are packed down toward + the beginning of the collection, and the collection’s + global heap object 0 is created (if possible), or its size is + increased to account for the recently freed space. There are + no gaps between objects in each collection, with the possible + exception of the final space in the collection, if it is not + large enough to hold the header for the collection’s + global heap object 0. These features address goal C. +</p> + +<p>The HDF5 Library creates global heap collections as needed, so there may + be multiple collections throughout the file. The set of all of them is + abstractly called the “global heap”, although they do not actually link + to each other, and there is no global place in the file where you can + discover all of the collections. The collections are found simply by + finding a reference to one through another object in the file. For + example, data of variable-length datatype elements is stored in the + global heap and is accessed via a global heap ID. The format for + global heap IDs is described at the end of this section. +</p> + +<p>For more information on global heaps for virtual datasets, see + <a href="#GlobalHeapVDS">“Disk Format: Level 1F - Global Heap + Block for Virtual Datasets.”</a></p> +<br /> + +<div align="center"> + <table class="format"> + <caption> + Layout: A Global Heap Collection + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Collection Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 2<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />...<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object <em>N</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Global Heap Object 0 (free space)<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: A Global Heap Collection + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>GCOL</code>” + is used to indicate the + beginning of a collection. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>Each collection has its own version number so that new + collections can be added to old files. This document + describes version one (1) of the collections (there is no + version zero (0)). + </p> + </td> + </tr> + + <tr> + <td><p>Collection Size</p></td> + <td> + <p>This is the size in bytes of the entire collection + including this field. The default (and minimum) + collection size is 4096 bytes which is a typical file + system block size. This allows for 127 16-byte heap + objects plus their overhead (the collection header of 16 bytes + and the 16 bytes of information about each heap object). + </p> + </td> + </tr> + + <tr> + <td><p>Global Heap Object 1 through <em>N</em></p></td> + <td> + <p>The objects are stored in any order with no + intervening unused space. + </p> + </td> + </tr> + + <tr> + <td><p>Global Heap Object 0</p></td> + <td> + <p>Global Heap Object 0 (zero), when present, represents the free + space in the collection. Free space always appears at the end of + the collection. If the free space is too small to store the header + for Object 0 (described below) then the header is implied and is not + written. + <p> + The field <em>Object Size</em> for Object 0 indicates the + amount of possible free space in the collection including the 16-byte + header size of Object 0. + </p> + </td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Global Heap Object + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="2">Heap Object Index</td> + <td colspan="2">Reference Count</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Object Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Object Data<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Global Heap Object + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Heap Object Index</p></td> + <td> + <p>Each object has a unique identification number within a + collection. The identification numbers are chosen so that + new objects have the smallest value possible with the + exception that the identifier <code>0</code> always refers to the + object which represents all free space within the + collection. + </p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>All heap objects have a reference count field. An + object which is referenced from some other part of the + file will have a positive reference count. The reference + count for Object 0 is always zero. + </p> + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td> + <p>Zero padding to align next field on an 8-byte boundary. + </p> + </td> + </tr> + + <tr> + <td><p>Object Size</p></td> + <td> + <p>This is the size of the object data stored for the object. + The actual storage space allocated for the object data is rounded + up to a multiple of eight. + </p> + </td> + </tr> + + <tr> + <td><p>Object Data</p></td> + <td> + <p>The object data is treated as a one-dimensional array + of bytes to be interpreted by the caller. + </p> + </td> + </tr> + </table> + +</div> + +<br /> +<br /> +<br /> +<p> + <a name="GlobalHeapID"></a> + The format for the ID used to locate an object in the global heap is + described here:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Global Heap ID + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Collection Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Object Index</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Global Heap ID + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Collection Address</p></td> + <td> + <p>This field is the address of the global heap collection + where the data object is stored. + </p> + </td> + </tr> + + <tr> + <td><p>ID</p></td> + <td> + <p>This field is the index of the data object within the + global heap collection. + </p> + </td> + </tr> + + </table> +</div> + + + +<h3><a name="GlobalHeapVDS"> III.F. Disk Format: Level 1F - Global + Heap Block for Virtual Datasets</a></h3> + +<p>The layout for the global heap block used with virtual datasets is + described below. For more information on global heaps, see + <a href="#GlobalHeap"></a>“Disk Format: Level 1E - Global Heap.”</p> + +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Global Heap Block for Virtual Dataset + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Num Entries<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Filename #1 <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Dataset #1 <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Selection #1 <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Virtual Selection #1 <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Filename #n <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Dataset #n <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Source Selection #n <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Virtual Selection #n <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Global Heap Block for Virtual Dataset + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for the block; the value is 0.</p> + </td> + </tr> + + <tr> + <td><p>Num Entries</p></td> + <td><p>The number of entries in the block.</p> + </td> + </tr> + + <tr> + <td><p>Source Filename #n</p></td> + <td> + <p>The source file name where the source dataset is located. + </p> + </td> + </tr> + + <tr> + <td><p>Source Dataset #n</p></td> + <td><p>The source dataset name that is mapped to the + virtual dataset.</p></td> + </tr> + + <tr> + <td><p>Source Selection #n</p></td> + <td> + <p>The <a href="#DataspaceSEL">dataspace selection</a> in the + source dataset that is mapped to the virtual selection. + </p> + </td> + </tr> + + <tr> + <td><p>Virtual Selection #n</p></td> + <td> + <p>This is the <a href="#DataspaceSEL">dataspace selection</a> in the virtual dataset that is + mapped to the source selection. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the block.</p> + </td> + </tr> + + </table> +</div> +<br> + +<h3><a name="FractalHeap"> + III.G. Disk Format: Level 1G - Fractal Heap</a></h3> + +<p> + Each fractal heap consists of a header and zero or more direct and + indirect blocks (described below). The header contains general + information as well as + initialization parameters for the doubling table. The <em>Address + of Root Block</em> field in the header points to the first direct or + indirect block in the heap. +</p> + +<p> + Fractal heaps are based on a data structure called a <em>doubling + table</em>. A doubling table provides a mechanism for quickly + extending an array-like data structure that minimizes the number of + empty blocks in the heap, while retaining very fast lookup of any + element within the array. More information on fractal heaps and + doubling tables can be found in the RFC + “<a href="Supplements/FractalHeap/PrivateHeap.pdf">Private + Heaps in HDF5</a>.” +</p> + +<p> + The fractal heap implements the doubling table structure with + indirect and direct blocks. + Indirect blocks in the heap do not actually contain data for + objects in the heap, their “size” is abstract - + they represent the indexing structure for locating the + direct blocks in the doubling table. + Direct blocks + contain the actual data for objects stored in the heap. +</p> + +<p> + All indirect blocks have a constant number of block entries in each + row, called the <em>width</em> of the doubling table + (see <em>Table Width</em> field in the header). + + The number + of rows for each indirect block in the heap is determined by the + size of the block that the indirect block represents in the + doubling table (calculation of this is shown below) and is + constant, except for the “root” + indirect block, which expands and shrinks its number of rows as + needed. +</p> + +<p> + Blocks in the first <em>two</em> rows of an indirect block + are <em>Starting Block Size</em> number of bytes in size. + For example, if the row <em>width</em> of the doubling table is 4, + then the first eight block entries in the + indirect block are <em>Starting Block Size</em> number of bytes in size. + The blocks in each subsequent row are twice the size of + the blocks in the previous row. In other words, blocks in + the third row are twice the <em>Starting Block Size</em>, + blocks in the fourth row are four times the + <em>Starting Block Size</em>, and so on. Entries for + blocks up to the <em>Maximum Direct Block Size</em> point to + direct blocks, and entries for blocks greater than that size + point to further indirect blocks (which have their own + entries for direct and indirect blocks). + <em>Starting Block Size</em> and + <em>Maximum Direct Block Size</em> are fields + stored in the header. +</p> + +<p> + The number of rows of blocks, <em>nrows</em>, in an + indirect block is calculated by the following expression: + <br /> <br /> + <em>nrows</em> = (log<sub>2</sub>(<em>block_size</em>) - + log<sub>2</sub>(<em><Starting Block Size></em>)) + 1 +</p> +where <em>block_size</em> is the size of the block that the indirect block +represents in the doubling table. +For example, to represent a block with <em>block_size</em> equals to 1024, +and <em>Starting Block Size</em> equals to 256, +three rows are needed. +<p> + The maximum number of rows of direct blocks, <em>max_dblock_rows</em>, + in any indirect block of a fractal heap is given by the + following expression: + <br /> <br /> + <em>max_dblock_rows</em> = + (log<sub>2</sub>(<em><Maximum Direct Block Size></em>) - + log<sub>2</sub>(<em><Starting Block Size></em>)) + 2 +</p> +<p> + Using the computed values for <em>nrows</em> and + <em>max_dblock_rows</em>, along with the <em>width</em> of the + doubling table, the number of direct and indirect block entries + (<em>K</em> and <em>N</em> in the indirect block description, below) + in an indirect block can be computed: + <br /> <br /> + <em>K</em> = MIN(<em>nrows</em>, <em>max_dblock_rows</em>) * + <em><Table Width></em> + + <br /> <br /> + If <em>nrows</em> is less than or equal to <em>max_dblock_rows</em>, + <em>N</em> is 0. Otherwise, <em>N</em> is simply computed: + <br /> <br /> + <em>N</em> = <em>K</em> - (<em>max_dblock_rows</em> * + <em><Table Width></em>) +</p> + +<p> + The size of indirect blocks on disk is determined by the number + of rows in the indirect block (computed above). The size of direct + blocks on disk is exactly the size of the block in the doubling + table. +</p> +<br> + +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Heap ID Length</td> + <td colspan="2">I/O Filters’ Encoded Length</td> + </tr> + + <tr> + <td>Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Maximum Size of Managed Objects</td> + </tr> + + <tr> + <td colspan="4"><br />Next Huge Object ID<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />v2 B-tree Address of Huge Objects<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Free Space in Managed Blocks<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Managed Block Free Space Manager<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Managed Space in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Amount of Allocated Managed Space in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset of Direct Block Allocation Iterator in Managed Space<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Managed Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Huge Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Huge Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Table Width</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Starting Block Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Direct Block Size<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Maximum Heap Size</td> + <td colspan="2">Starting # of Rows in Root Indirect Block</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Root Block<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Current # of Rows in Root Indirect Block</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Filtered Root Direct Block <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">I/O Filter Mask<em> (optional)</em></td> + </tr> + + <tr> + <td colspan="4">I/O Filter Information<em> (optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap Header + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FRHP</code>” + is used to indicate the + beginning of a fractal heap header. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap ID Length</p></td> + <td> + <p>This is the length in bytes of heap object IDs for this heap.</p> + </td> + </tr> + + <tr> + <td><p>I/O Filters’ Encoded Length</p></td> + <td> + <p>This is the size in bytes of the encoded <em>I/O Filter Information</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is the heap status flag and is a bit field + indicating additional information about the fractal heap. + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the ID value to use for huge object has wrapped + around. If the value for the <em>Next Huge Object ID</em> + has wrapped around, each new huge object inserted into the + heap will require a search for an ID value. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the direct blocks in the heap are checksummed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Size of Managed Objects</p></td> + <td> + <p>This is the maximum size of managed objects allowed in the heap. + Objects greater than this this are ‘huge’ objects and will be + stored in the file directly, rather than in a direct block for + the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Next Huge Object ID</p></td> + <td> + <p>This is the next ID value to use for a huge object in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>v2 B-tree Address of Huge Objects</p></td> + <td> + <p>This is the address of the <a href="#V2Btrees">v2 B-tree</a> + used to track huge objects in the heap. The type of records + stored in the <em>v2 B-tree</em> will + be determined by whether the address and length of a huge object + can fit into a heap ID (if yes, it is a “directly” accessed + huge object) and whether there is a filter used on objects + in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Free Space in Managed Blocks</p></td> + <td> + <p>This is the total amount of free space in managed direct blocks + (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Address of Managed Block Free Space Manager</p></td> + <td> + <p>This is the address of the + <em><a href="#FreeSpaceManager">Free-space Manager</a></em> for + managed blocks. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Managed Space in Heap</p></td> + <td> + <p>This is the total amount of managed space in the heap (in bytes), + essentially the upper bound of the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Amount of Allocated Managed Space in Heap</p></td> + <td> + <p>This is the total amount of managed space (in bytes) actually + allocated in + the heap. This can be less than the <em>Amount of Managed Space + in Heap</em> field, if some direct blocks in the heap’s linear + address space are not allocated. + </p> + </td> + </tr> + + <tr> + <td><p>Offset of Direct Block Allocation Iterator in Managed Space</p></td> + <td> + <p>This is the linear heap offset where the next direct + block should be allocated at (in bytes). This may be less than + the <em>Amount of Managed Space in Heap</em> value because the + heap’s address space is increased by a “row” of direct blocks + at a time, rather than by single direct block increments. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Managed Objects in Heap</p></td> + <td> + <p>This is the number of managed objects in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Huge Objects in Heap</p></td> + <td> + <p>This is the total size of huge objects in the heap (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Number of Huge Objects in Heap</p></td> + <td> + <p>This is the number of huge objects in the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Tiny Objects in Heap</p></td> + <td> + <p>This is the total size of tiny objects that are packed in heap + IDs (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Number of Tiny Objects in Heap</p></td> + <td> + <p>This is the number of tiny objects that are packed in heap IDs. + </p> + </td> + </tr> + + <tr> + <td><p>Table Width</p></td> + <td> + <p>This is the number of columns in the doubling table for managed + blocks. This value must be a power of two. + </p> + </td> + </tr> + + <tr> + <td><p>Starting Block Size</p></td> + <td> + <p>This is the starting block size to use in the doubling table for + managed blocks (in bytes). This value must be a power of two. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Direct Block Size</p></td> + <td> + <p>This is the maximum size allowed for a managed direct block. + Objects inserted into the heap that are larger than this value + (less the number of bytes of direct block prefix/suffix) + are stored as ‘huge’ objects. This value must be a power of + two. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Heap Size</p></td> + <td> + <p>This is the maximum size of the heap’s linear address space for + managed objects (in bytes). The value stored is the log2 of + the actual value, that is: the number of bits of the address space. + ‘Huge’ and ‘tiny’ objects are not counted in this value, since + they do not store objects in the linear address space of the + heap. + </p> + </td> + </tr> + + <tr> + <td><p>Starting # of Rows in Root Indirect Block</p></td> + <td> + <p>This is the starting number of rows for the root indirect block. + A value of 0 indicates that the root indirect block will have + the maximum number of rows needed to address the heap’s <em>Maximum + Heap Size</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Root Block</p></td> + <td> + <p>This is the address of the root block for the heap. It can + be the <a href="#UndefinedAddress">undefined address</a> if + there is no data in the heap. It either points to a direct + block (if the <em>Current # of Rows in the Root Indirect + Block</em> value is 0), or an indirect block. + </p> + </td> + </tr> + + <tr> + <td><p>Current # of Rows in Root Indirect Block</p></td> + <td> + <p>This is the current number of rows in the root indirect block. + A value of 0 indicates that <em>Address of Root Block</em> + points to direct block instead of indirect block. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Filtered Root Direct Block</p></td> + <td> + <p>This is the size of the root direct block, if filters are + applied to heap objects (in bytes). This field is only + stored in the header if the <em>I/O Filters’ Encoded Length</em> + is greater than 0. + </p> + </td> + </tr> + + <tr> + <td><p>I/O Filter Mask</p></td> + <td> + <p>This is the filter mask for the root direct block, if filters + are applied to heap objects. This mask has the same format as + that used for the filter mask in chunked raw data records in a + <a href="#V1Btrees">v1 B-tree</a>. + This field is only + stored in the header if the <em>I/O Filters’ Encoded Length</em> + is greater than 0. + </p> + </td> + </tr> + + <tr> + <td><p>I/O Filter Information</p></td> + <td> + <p>This is the I/O filter information encoding direct blocks and + huge objects, if filters are applied to heap objects. This + field is encoded as a <a href="#FilterMessage">Filter Pipeline</a> + message. + The size of this field is determined by <em>I/O Filters’ + Encoded Length</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the header.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap Direct Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Object Data <em>(variable size)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap Direct Block + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FHDB</code>” + is used to indicate the + beginning of a fractal heap direct block. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode + this field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is + principally used for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the direct block.</p> + <p>This field is only present if bit 1 of <em>Flags</em> in the + heap’s header is set.</p> + </td> + </tr> + + <tr> + <td><p>Object Data</p></td> + <td> + <p>This section of the direct block stores the actual data for + objects in the heap. The size of this section is determined by + the direct block’s size minus the size of the other fields + stored in the direct block (for example, the <em>Signature</em>, + <em>Version</em>, and others including the <em>Checksum</em> if it is + present). + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap Indirect Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #0 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #0 <em>(optional)</em> <sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #0 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #1 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #1 <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #1 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4"><br />Child Direct Block #K-1 Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #K-1 <em>(optional)</em><sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #K-1 <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #0 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #1 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4"><br />Child Indirect Block #N-1 Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap Indirect Block + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FHIB</code>” is used to + indicate the beginning of a fractal heap indirect block. This + gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode + this field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is + principally used for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Child Direct Block #K Address</p></td> + <td> + <p>This field is the address of the child direct block. + The size of the [uncompressed] direct block can be computed by + its offset in the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Filtered Direct Block #K</p></td> + <td> + <p>This is the size of the child direct block after passing through + the I/O filters defined for this heap (in bytes). If no I/O + filters are present for this heap, this field is not present. + </p> + </td> + </tr> + <tr> + <td><p>Filter Mask for Direct Block #K</p></td> + <td> + <p>This is the I/O filter mask for the filtered direct block. + This mask has the same format as that used for the filter mask + in chunked raw data records in a <a href="#V1Btrees">v1 B-tree</a>. + If no I/O filters are present for this heap, this field is not + present. + </p> + </td> + </tr> + + <tr> + <td><p>Child Indirect Block #N Address</p></td> + <td> + <p>This field is the address of the child indirect block. + The size of the indirect block can be computed by + its offset in the heap’s linear address space. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the indirect block.</p> + </td> + </tr> + + </table> + +</div> + +<br /> +<p>An object in the fractal heap is identified by means of a fractal heap ID, + which encodes information to locate the object in the heap. + Currently, the fractal heap stores an object in one of three ways, + depending on the object’s size:</p> + +<div align="center"> + <table class="list80"> + <tr> + <th width="20%">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center">Tiny</td> + <td> + <p>When an object is small enough to be encoded in the + heap ID, the object’s data is embedded in the fractal + heap ID itself. There are two sub-types for this type of + object: normal and extended. The sub-type for tiny heap + IDs depends on whether the heap ID is large enough to + store objects greater than 16 bytes or not. If the + heap ID length is 18 bytes or smaller, the + ‘normal’ tiny heap ID form is used. If the + heap ID length is greater than 18 bytes in length, the + “extended” form is used. See the format + description below for both sub-types. + </p> + </td> + </tr> + + <tr> + <td align="center">Huge</td> + <td> + <p>When the size of an object is larger than <em>Maximum Size of + Managed Objects</em> in the <em>Fractal Heap Header</em>, the + object’s data is stored on its own in the file and the object + is tracked/indexed via a version 2 B-tree. All huge objects + for a particular fractal heap use the same v2 B-tree. All huge + objects for a particular fractal heap use the same format for + their huge object IDs. + </p> + + <p>Depending on whether the IDs for a heap are large enough to hold + the object’s retrieval information and whether I/O pipeline filters + are applied to the heap’s objects, 4 sub-types are derived for + huge object IDs for this heap:</p> + + <div align="center"> + <table class="list"> + <tr> + <th align="left" width="35%">Sub-type</th> + <th align="left">Description</th> + </tr> + + <tr> + <td align="left">Directly accessed, non-filtered</td> + <td> + <p>The object’s address and length are embedded in the + fractal heap ID itself and the object is directly accessed + from them. This allows the object to be accessed without + resorting to the B-tree. + </p> + </td> + </tr> + + <tr> + <td align="left">Directly accessed, filtered</td> + <td> + <p>The filtered object’s address, length, filter mask and + de-filtered size are embedded in the fractal heap ID itself + and the object is accessed directly with them. This allows + the object to be accessed without resorting to the B-tree. + </p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, non-filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the address and length from + the version 2 B-tree for huge objects. Then, the address + and length are used to access the object. + </p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the filtered object’s + address, length, filter mask and de-filtered size from the + version 2 B-tree for huge objects. Then, this information + is used to access the object. + </p> + </td> + </tr> + </table> + </div> + + </td> + </tr> + + <tr> + <td align="center">Managed</td> + <td> + <p>When the size of an object does not meet the above two + conditions, the object is stored and managed via the direct and + indirect blocks based on the doubling table. + </p> + </td> + </tr> + </table> +</div> + + +<br /> +<p>The specific format for each type of heap ID is described below: +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Tiny Objects (Sub-type 1 - + ‘Normal’) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version, Type, and Length</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Tiny Objects (Sub-type 1 - + ‘Normal’) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version, Type, and Length</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>The length of the tiny object. The value stored + is one less than the actual length (since zero-length + objects are not allowed to be stored in the heap). + For example, an object of actual length 1 has an + encoded length of 0, an object of actual length 2 + has an encoded length of 1, and so on. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td> + <p>This is the data for the object. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Tiny Objects (Sub-type 2 - + ‘Extended’) + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version, Type, and Length</td> + <td>Extended Length</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Data <em>(variable size)</em></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Tiny Objects (Sub-type 2 - + ‘Extended’) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version, Type, and Length</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>These 4 bits, together with the next byte, form an + unsigned 12-bit integer for holding the length of the + object. These 4-bits are bits 8-11 of the 12-bit integer. + See description for the <em>Extended Length</em> field below. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Extended Length</p></td> + <td> + <p>This byte, together with the 4 bits in the previous byte, + forms an unsigned 12-bit integer for holding the length of + the tiny object. These 8 bits are bits 0-7 of the 12-bit + integer formed. The value stored is one less than the actual + length (since zero-length objects are not allowed to be + stored in the heap). For example, an object of actual length + 1 has an encoded length of 0, an object of actual length + 2 has an encoded length of 1, and so on. + </p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td> + <p>This is the data for the object. + </p> + </td> + </tr> + + </table> +</div> + + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Huge Objects (Sub-types 1 and 2): + Indirectly Accessed, Non-filtered/Filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version and Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />v2 B-tree Key<sup>L</sup><em> (variable size)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Huge Objects (Sub-types 1 and 2): + Indirectly Accessed, Non-filtered/Filtered + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version and Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>v2 B-tree Key</p></td> + <td><p>This field is the B-tree key for retrieving the information + from the version 2 B-tree for huge objects needed to access the + object. See the description of <a href="#V2Btrees">v2 B-tree</a> + records sub-types 1 and 2 for a description of the fields. New key + values are derived from <em>Next Huge Object ID</em> in the + <em>Fractal Heap Header</em>.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Huge Objects (Sub-type 3): + Directly Accessed, Non-filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version and Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Huge Objects (Sub-type 3): + Directly Accessed, Non-filtered + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version and Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This field is the address of the object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the object in the file.</p> + </td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Huge Objects (Sub-type 4): + Directly Accessed, Filtered + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version and Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filter Mask</td> + </tr> + + <tr> + <td colspan="4"><br />De-filtered Size <sup>L</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Huge Objects (Sub-type 4): + Directly Accessed, Filtered + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version and Type</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This field is the address of the filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td><p>This field is the I/O pipeline filter mask for the + filtered object in the file.</p> + </td> + </tr> + + <tr> + <td><p>Filtered Size</p></td> + <td><p>This field is the size of the de-filtered object in the file.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap ID for Managed Objects + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version and Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Length <em>(variable size)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap ID for Managed Objects + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version and Type</p></td> + <td><p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document + describes version 0. + </td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Managed objects have a value of <code>0</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Offset</p></td> + <td><p>This field is the offset of the object in the heap. + This field’s size is the minimum number of bytes + necessary to encode the <em>Maximum Heap Size</em> value + (from the <em>Fractal Heap Header</em>). For example, if the + value of the <em>Maximum Heap Size</em> is less than 256 bytes, + this field is 1 byte in length, a <em>Maximum Heap Size</em> + of 256-65535 bytes uses a 2 byte length, and so on.</p></td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the object in the heap. It + is determined by taking the minimum value of <em>Maximum + Direct Block Size</em> and <em>Maximum Size of Managed + Objects</em> in the <em>Fractal Heap Header</em>. Again, + the minimum number of bytes needed to encode that value is + used for the size of this field.</p></td> + </tr> + </table> +</div> + +<h3><a name="FreeSpaceManager"> + III.H. Disk Format: Level 1H - Free-space Manager</a></h3> + +<p> + Free-space managers are used to describe space within a heap or + the entire HDF5 file that is not currently used for that heap or + file. +</p> + +<p> + The <em>free-space manager header</em> contains metadata information + about the space being tracked, along with the address of the list + of <em>free space sections</em> which actually describes the free + space. The header records information about free-space sections being + tracked, creation parameters for handling free-space sections of a + client, and section information used to locate the collection of + free-space sections. +</p> + +<p> + The <em>free-space section list</em> stores a collection of + free-space sections that is specific to each <em>client</em> of the + free-space manager. + + For example, the fractal heap is a client of the free space manager + and uses it to track unused space within the heap. There are 4 + types of section records for the fractal heap, each of which has + its own format, listed below. +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Free-space Manager Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Total Space Tracked<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Total Number of Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Serialized Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Number of Un-Serialized Sections<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="2">Number of Section Classes</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Shrink Percent</td> + <td colspan="2">Expand Percent</td> + </tr> + + <tr> + <td colspan="2">Size of Address Space</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Section Size <sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Serialized Section List<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Serialized Section List Used<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Allocated Size of Serialized Section List<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Free-space Manager Header + </caption> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FSHD</code>” + is used to indicate the beginning of the Free-space Manager + Header. This gives file consistency checking utilities a + better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Manager Header + and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>This is the client ID for identifying the user of this + free-space manager: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Fractal heap + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>File + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Total Space Tracked</p></td> + <td> + <p>This is the total amount of free space being tracked, in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Sections</p></td> + <td> + <p>This is the total number of free-space sections being tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Serialized Sections</p></td> + <td> + <p>This is the number of serialized free-space sections being + tracked. + </p> + </td> + </tr> + <tr> + <td><p>Number of Un-Serialized Sections</p></td> + <td> + <p>This is the number of un-serialized free-space sections being + managed. Un-serialized sections are created by the free-space + client when the list of sections is read in. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Section Classes</p></td> + <td> + <p>This is the number of section classes handled by this free space + manager for the free-space client. + </p> + </td> + </tr> + + <tr> + <td><p>Shrink Percent</p></td> + <td> + <p>This is the percent of current size to shrink the allocated + serialized free-space section list. + </p> + </td> + </tr> + + <tr> + <td><p>Expand Percent</p></td> + <td> + <p>This is the percent of current size to expand the allocated + serialized free-space section list. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Address Space</p></td> + <td> + <p>This is the size of the address space that free-space sections + are within. This is stored as the log<sub>2</sub> of the + actual value (in other words, the number of bits required + to store values within that address space). + </p> + </td> + </tr> + + <tr> + <td><p>Maximum Section Size</p></td> + <td> + <p>This is the maximum size of a section to be tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Address of Serialized Section List</p></td> + <td> + <p>This is the address where the serialized free-space section + list is stored. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Serialized Section List Used</p></td> + <td> + <p>This is the size of the serialized free-space section + list used (in bytes). This value must be less than + or equal to the <em>allocated size of serialized section + list</em>, below. + </p> + </td> + </tr> + + <tr> + <td><p>Allocated Size of Serialized Section List</p></td> + <td> + <p>This is the size of serialized free-space section list + actually allocated (in bytes). + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the free-space manager header.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<p>The free-space sections being managed are stored in a + <em>free-space section list</em>, described below. The sections + in the free-space section list are stored in the following way: + a count of the number of sections describing a particular size of + free space and the size of the free-space described (in bytes), + followed by a list of section description records; then another + section count and size, followed by the list of section + descriptions for that size; and so on.</p> + + +<div align="center"> + <table class="format"> + <caption> + Layout: Free-space Section List + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Free-space Manager Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #0 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #0 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #0 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #0 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> + + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> + + <tr> + <td colspan="4">Number of Section Records in Set #N-1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Size of Free-space Section Described in Record Set #N-1 <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #N-1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Data <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Offset<em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="1">Record Set #N-1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Data <em>(variable size)</td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Free-space Section List + </caption> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FSSE</code>” + is used to indicate the beginning of the Free-space Section + Information. This gives file consistency checking utilities + a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Section List + and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Free-space Manager Header Address</p></td> + <td> + <p>This is the address of the <em>Free-space Manager Header</em>. + This field is principally used for file + integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Section Records for Set #N</p></td> + <td> + <p>This is the number of free-space section records for set #N. + The length of this field is the minimum number of bytes needed + to store the <em>number of serialized sections</em> (from the + <em>free-space manager header</em>). + </p> + + <p> + The number of sets of free-space section records is + determined by the <em>size of serialized section list</em> in + the <em>free-space manager header</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Section Size for Record Set #N</p></td> + <td> + <p>This is the size (in bytes) of the free-space section described + for <em>all</em> the section records in set #N. + </p> + + <p> + The length of this field is the minimum number of bytes needed + to store the <em>maximum section size</em> (from the + <em>free-space manager header</em>). + </p> + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Offset</p></td> + <td> + <p>This is the offset (in bytes) of the free-space section within + the client for the free-space manager. + </p> + + <p> + The length of this field is the minimum number of bytes needed + to store the <em>size of address space</em> (from the + <em>free-space manager header</em>). + </p> + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Type</p></td> + <td> + <p>This is the type of the section record, used to decode the + <em>record set #N section #K data</em> information. The defined + record type for <em>file</em> client is: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>File’s section (a range of actual bytes in file) + </td> + </tr> + <tr> + <td align="center"><code>1+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + <p>The defined record types for a <em>fractal heap</em> client are: + + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Fractal heap “single” section + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Fractal heap “first row” section + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Fractal heap “normal row” section + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Fractal heap “indirect” section + </td> + </tr> + + <tr> + <td align="center"><code>4+</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Record Set #N Section #K Data</p></td> + <td> + <p>This is the section-type specific information for each record + in the record set, described below. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the <em>Free-space Section List</em>. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<p> + The section-type specific data for each free-space section record is + described below: +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: File’s Section Data Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap “Single” Section Data Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap “First Row” Section Data + Record + </caption> + + <tr> + <td colspan="4"><em>Same format as “indirect” + section data</em></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap “Normal Row” Section Data + Record + </caption> + + <tr> + <td colspan="4"><em>No additional record data stored</em></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fractal Heap “Indirect” Section + Data Record + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Fractal Heap Indirect Block Offset <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="2">Block Start Row</td> + <td colspan="2">Block Start Column</td> + </tr> + + <tr> + <td colspan="2">Number of Blocks</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fractal Heap “Indirect” Section + Data Record + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Fractal Heap Block Offset</p></td> + <td> + <p>The offset of the indirect block in the fractal heap’s address + space containing the empty blocks. + </p> + <p> + The number of bytes used to encode this field is the minimum + number of bytes needed to encode values for the <em>Maximum + Heap Size</em> (in the fractal heap’s header). + </p> + </td> + </tr> + + <tr> + <td><p>Block Start Row</p></td> + <td> + <p>This is the row that the empty blocks start in. + </p> + </td> + </tr> + + <tr> + <td><p>Block Start Column</p></td> + <td> + <p>This is the column that the empty blocks start in. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Blocks</p></td> + <td> + <p>This is the number of empty blocks covered by the section. + </p> + </td> + </tr> + </table> +</div> + +<h3><a name="SOHMTable"> + III.I. Disk Format: Level 1I - Shared Object Header Message Table</a></h3> + +<p> + The <em>shared object header message table</em> is used to locate + object + header messages that are shared between two or more object headers + in the file. Shared object header messages are stored and indexed + in the file in one of two ways: indexed sequentially in a + <em>shared header message list</em> or indexed with a v2 B-tree. + The shared messages themselves are either stored in a fractal + heap (when two or more objects share the message), or remain in an + object’s header (when only one object uses the message currently, + but the message can be shared in the future). +</p> + +<p> + The <em>shared object header message table</em> + contains a list of shared message index headers. Each index header + records information about the version of the index format, the index + storage type, flags for the message types indexed, the number of + messages in the index, the address where the index resides, + and the fractal heap address if shared messages are stored there. +</p> + +<p> + Each index can be either a list or a v2 B-tree and may transition + between those two forms as the number of messages in the index + varies. Each shared message record contains information used to + locate the shared message from either a fractal heap or an object + header. The types of messages that can be shared are: <em>Dataspace, + Datatype, Fill Value, Filter Pipeline and Attribute</em>. +</p> + +<p> + The <em>shared object header message table</em> is pointed to + from a <a href="#SOHMTableMessage">shared message table</a> message + in the superblock extension for a file. This message stores the + version of the table format, along with the number of index headers + in the table. +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Object Header Message Table + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version for index #0</td> + <td>Index Type for index #0</td> + <td colspan="2">Message Type Flags for index #0</td> + </tr> + + <tr> + <td colspan="4">Minimum Message Size for index #0</td> + </tr> + + <tr> + <td colspan="2">List Cutoff for index #0</td> + <td colspan="2">v2 B-tree Cutoff for index #0</td> + </tr> + + <tr> + <td colspan="2">Number of Messages for index #0</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #0<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #0<br /><br /></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td>Version for index #N-1</td> + <td>Index Type for index #N-1</td> + <td colspan="2">Message Type Flags for index #N-1</td> + </tr> + + <tr> + <td colspan="4">Minimum Message Size for index #N-1</td> + </tr> + + <tr> + <td colspan="2">List Cutoff for index #N-1</td> + <td colspan="2">v2 B-tree Cutoff for index #N-1</td> + </tr> + + <tr> + <td colspan="2">Number of Messages for index #N-1</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #N-1<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #N-1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Object Header Message Table + </caption> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SMTB</code>” + is used to indicate the beginning of the Shared Object + Header Message table. This gives file consistency checking + utilities a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version for index #N</p></td> + <td> + <p>This is the version number for the list of shared object header message + indexes and this document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Index Type for index #N</p></td> + <td> + <p>The type of index can be an unsorted list or a v2 B-tree. + </p> + </td> + </tr> + + <tr> + <td><p>Message Type Flags for index #N</p></td> + <td> + <p>This field indicates the type of messages tracked in the index, + as follows: + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the index tracks <em>Dataspace Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the message tracks <em>Datatype Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, the message tracks <em>Fill Value Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, the message tracks <em>Filter Pipeline Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, the message tracks <em>Attribute Messages</em>. + </td> + </tr> + <tr> + <td align="center"><code>5-15</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + + <p> + An index can track more than one type of message, but each type + of message can only by in one index. + </p> + </td> + </tr> + + <tr> + <td><p>Minimum Message Size for index #N</p></td> + <td> + <p>This is the message size sharing threshold for the index. + If the encoded size of the message is less than this value, the + message is not shared. + </p> + </td> + </tr> + + <tr> + <td><p>List Cutoff for index #N</p></td> + <td> + <p>This is the cutoff value for the indexing of messages to + switch from a list to a v2 B-tree. If the number of messages + is greater than this value, the index should be a v2 B-tree. + </p> + </td> + </tr> + <tr> + <td><p>v2 B-tree Cutoff for index #N</p></td> + <td> + <p>This is the cutoff value for the indexing of messages + to switch from a v2 B-tree back to a list. If the number + of messages is less than this value, the index should be + a list. + </p> + </td> + </tr> + + <tr> + <td><p>Number of Messages for index #N</p></td> + <td> + <p>The number of shared messages being tracked for the index. + </p> + </td> + </tr> + + <tr> + <td><p>Index Address for index #N</p></td> + <td> + <p>This field is the address of the list or v2 B-tree where the + index nodes reside. + </p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address for index #N</p></td> + <td> + <p>This field is the address of the fractal heap if shared messages + are stored there. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the table.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<p> + Shared messages are indexed either with a <em>shared message record + list</em>, described below, or using a v2 B-tree (using record type 7). + The number of records in the <em>shared message record list</em> is + determined in the index’s entry in the <em>shared object header message + table</em>. +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message Record List + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #0</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #1</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Shared Message Record #N-1</td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message Record List + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>SMLI</code>” + is used to indicate the beginning of a list of index nodes. + This gives file consistency checking utilities a better + chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Shared Message Record #N</p></td> + <td> + <p>The record for locating the shared message, either in the + fractal heap for the index, or an object header (see format for + <em>index nodes</em> below). + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the list. + </p> + </td> + </tr> + + </table> +</div> + +<br /> +<p> + The record for each shared message in an index is stored in one + of the following forms: +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message Record for Messages Stored in a + Fractal Heap + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Hash Value</td> + </tr> + + <tr> + <td colspan="4">Reference Count</td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap ID<br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message Record for Messages Stored in a + Fractal Heap + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 0 indicating that the message is stored in + the heap. + </p> + </td> + </tr> + + <tr> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message. + </p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td> + <p>This is the number of times the message is used in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap ID</p></td> + <td> + <p>This is an 8-byte fractal heap ID for the message as stored in + the fractal heap for the index. + </p> + </td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message Record for Messages Stored in an + Object Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Hash Value</td> + </tr> + + <tr> + <td>Reserved</td> + <td>Message Type</td> + <td colspan="2">Creation Index</td> + </tr> + + <tr> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message Record for Messages Stored in an + Object Header + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 1 indicating that the message is stored in + an object header. + </p> + </td> + </tr> + + <tr> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message. + </p> + </td> + </tr> + + <tr> + <td><p>Message Type</p></td> + <td> + <p>This is the message type in the object header. + </p> + </td> + </tr> + + <tr> + <td><p>Creation Index</p></td> + <td> + <p>This is the creation index of the message within the object + header. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>This is the address of the object header where the message is + located. + </p> + </td> + </tr> + </table> +</div> + +<h2><a name="DataObject"> + IV. Disk Format: Level 2 - Data Objects </a></h2> + +<p>Data objects contain the “real” user-visible information in the file. + These objects compose the scientific data and other information which + are generally thought of as “data” by the end-user. All the + other information in the file is provided as a framework for + storing and accessing these data objects. +</p> + +<p>A data object is composed of header and data + information. The header information contains the information + needed to interpret the data information for the object as + well as additional “metadata” or pointers to additional + “metadata” used to describe or annotate each object. +</p> + +<h3><a name="ObjectHeader"> + IV.A. Disk Format: Level 2A - Data Object Headers</a></h3> + +<p>The header information of an object is designed to encompass + all of the information about an object, except for the data itself. + This information includes the dataspace, the datatype, information + about how the data is stored on disk (in external files, compressed, + broken up in blocks, and so on), as well as other information used + by the library to speed up access to the data objects or maintain + a file’s integrity. Information stored by user applications + as attributes is also stored in the object’s header. The header + of each object is not necessarily located immediately prior to the + object’s data in the file and in fact may be located in any + position in the file. The order of the messages in an object header + is not significant.</p> + +<p>Object headers are composed of a prefix and a set of messages. The + prefix contains the information needed to interpret the messages and + a small amount of metadata about the object, and the messages contain + the majority of the metadata about the object. +</p> + +<h3><a name="ObjectHeaderPrefix"> + IV.A.1. Disk Format: Level 2A1 - Data Object Header Prefix</a></h3> + + + +<h4><a name="V1ObjectHeaderPrefix"> + IV.A.1.a. Version 1 Data Object Header Prefix</a></h4> + +<p>Header messages are aligned on 8-byte boundaries for version 1 + object headers. +</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Version 1 Object Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Total Number of Header Messages</td> + </tr> + + <tr> + <td colspan="4">Object Reference Count</td> + </tr> + + <tr> + <td colspan="4">Object Header Size</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="2">Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + </tr> + + <tr> + <td>Header Message #1 Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td colspan="2">Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + </tr> + + <tr> + <td>Header Message #n Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 1 Object Header + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + information in the object header. When the format of the + object header is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + is version one (1) (there was no version zero (0)) of the + object header. + </p> + </td> + </tr> + + <tr> + <td><p>Total Number of Header Messages</p></td> + <td> + <p>This value determines the total number of messages listed in + object headers for this object. This value includes the messages + in continuation messages for this object. + </p> + </td> + </tr> + + <tr> + <td><p>Object Reference Count</p></td> + <td> + <p>This value specifies the number of “hard links” to this object + within the current file. References to the object from external + files, “soft links” in this file and object references in this + file are not tracked. + </p> + </td> + </tr> + + <tr> + <td><p>Object Header Size</p></td> + <td> + <p>This value specifies the number of bytes of header message data + following this length field that contain object header messages + for this object header. This value does not include the size of + object header continuation blocks for this object elsewhere in the + file. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>This value specifies the type of information included in the + following header message data. The message types for + header messages are defined in sections below. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size includes + padding bytes to make the message a multiple of eight + bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>This is a bit field with the following definition: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the message data is constant. This is used + for messages like the datatype message of a dataset. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the message is <em>shared</em> and stored + in another location than the object header. The Header + Message Data field contains a Shared Message + (described in the <a href="#ObjectHeaderMessages">Data Object Header Messages</a> + section below) + and the Size of Header Message Data field + contains the size of that Shared Message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, the message should not be shared. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, the HDF5 decoder should fail to open this object + if it does not understand the message’s type and the file + is open with permissions allowing write access to the file. + (Normally, unknown messages can just be ignored by HDF5 + decoders) + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, the HDF5 decoder should set bit 5 of this + message’s flags (in other words, this bit field) + if it does not understand the message’s type + and the object is modified in any way. (Normally, + unknown messages can just be ignored by HDF5 + decoders) + </td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, this object was modified by software that did not + understand this message. + (Normally, unknown messages should just be ignored by HDF5 + decoders) (Can be used to invalidate an index or a similar + feature) + </td> + </tr> + <tr> + <td align="center"><code>6</code></td> + <td>If set, this message is shareable. + </td> + </tr> + <tr> + <td align="center"><code>7</code></td> + <td>If set, the HDF5 decoder should always fail to open this + object if it does not understand the message’s type (whether + it is open for read-only or read-write access). (Normally, + unknown messages can just be ignored by HDF5 decoders) + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>The format and length of this field is determined by the + header message type and size respectively. Some header + message types do not require any data and this information + can be eliminated by setting the length of the message to + zero. The data is padded with enough zeroes to make the + size a multiple of eight. + </p> + </td> + </tr> + </table> +</div> + +<h4><a name="V2ObjectHeaderPrefix"> + IV.A.1.b. Version 2 Data Object Header Prefix</a></h4> + +<p>Note that the “total number of messages” field has been dropped from + the data object header prefix in this version. The number of messages + in the data object header is just determined by the messages encountered + in all the object header blocks.</p> + +<p>Note also that the fields and messages in this version of data object + headers have <em>no</em> alignment or padding bytes inserted - they are + stored packed together.</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 Object Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Access time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Modification Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Change Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Birth Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Maximum # of compact attributes <em>(optional)</em></td> + <td colspan="2">Minimum # of dense attributes <em>(optional)</em></td> + </tr> + + <tr> + <td>Size of Chunk #0 <em>(variable size)</em></td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 Object Header + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>OHDR</code>” + is used to indicate the beginning of an object header. This + gives file consistency checking utilities a better chance + of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This field has a value of 2 indicating version 2 of the object header. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is a bit field indicating additional information + about the object header. + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>This two bit field determines the size of the + <em>Size of Chunk #0</em> field. The values are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The <em>Size of Chunk #0</em> field is 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The <em>Size of Chunk #0</em> field is 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The <em>Size of Chunk #0</em> field is 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The <em>Size of Chunk #0</em> field is 8 bytes. + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, attribute creation order is tracked.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, attribute creation order is indexed.</td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, non-default attribute storage phase change + values are stored.</td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, access, modification, change and birth times + are stored.</td> + </tr> + <tr> + <td align="center"><code>6-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Access Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s raw data was last accessed + (in other words, read or written). + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Modification Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after + the UNIX epoch when the object’s raw data was last + modified (in other words, written). + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Change Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s metadata was last changed. + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Birth Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object was created. + </p> + <p>This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum # of compact attributes</p></td> + <td> + <p>This is the maximum number of attributes to store in the compact + format before switching to the indexed format. + </p> + <p>This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Minimum # of dense attributes</p></td> + <td> + <p>This is the minimum number of attributes to store in the indexed + format before switching to the compact format. + </p> + <p>This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Chunk #0</p></td> + <td> + <p> + This unsigned value specifies the number of bytes of header + message data following this field that contain object header + information. + </p> + <p> + This value does not include the size of object header + continuation blocks for this object elsewhere in the file. + </p> + <p> + The length of this field varies depending on bits 0 and 1 of + the <em>flags</em> field. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message. The size of messages + in this version does <em>not</em> include any padding bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in. + </p> + <p>This field is present if bit 2 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p> + </td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an + object header message prefix (message type + message size + + message flags). + </p> + <p>Gaps are formed when a message (typically an attribute message) + in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved + into the earlier chunk. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk. + </p> + </td> + </tr> + </table> +</div> + +<p>The header message types and the message data associated with + them compose the critical “metadata” about each object. Some + header messages are required for each object while others are + optional. Some optional header messages may also be repeated + several times in the header itself, the requirements and number + of times allowed in the header will be noted in each header + message description below. +</p> + + +<h3><a name="ObjectHeaderMessages"> + IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> + +<p>Data object header messages are small pieces of metadata that are + stored in the data object header for each object in an HDF5 file. + Data object header messages provide the metadata required to describe + an object and its contents, as well as optional pieces of metadata + that annotate the meaning or purpose of the object. +</p> + +<p>Data object header messages are either stored directly in the data + object header for the object or are shared between multiple objects + in the file. When a message is shared, a flag in the <em>Message Flags</em> + indicates that the actual <em>Message Data</em> + portion of that message is stored in another location (such as another + data object header, or a heap in the file) and the <em>Message Data</em> + field contains the information needed to locate the actual information + for the message. +</p> + +<p> + The format of shared message data is described here:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message (Version 1) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in the format + of a shared object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6.1. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header + containing the message to be shared.</p> + </td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + + <caption> + Layout: Shared Message (Version 2) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message (Version 2) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in the format + of a shared object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.1 and after. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header + containing the message to be shared.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message (Version 3) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Location <em>(variable size)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message (Version 3) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number indicates changes in the format of shared + object message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8 and after. In this + version, the <em>Type</em> field can indicate that + the message is stored in the fractal heap. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message is not shared and is not shareable. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Message stored in file’s <em>shared object header message</em> + heap (a <em>shared</em> message). + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Message stored is not shared, but is sharable. + </td> + </tr> + + </table></p> + </td> + </tr> + + <tr> + <td><p>Location</p></td> + <td><p>This field contains either a <a href="#SizeOfOffsetsV0"> + <em>Size of Offsets</em></a>-bytes address of the object header + containing the message to be shared, or an 8-byte fractal heap + ID for the message in the file’s <em>shared object header + message</em> heap. + </p> + </td> + </tr> + </table> +</div> + + +<p>The following is a list of currently defined header messages: +</p> + +<h4><a name="NILMessage">IV.A.2.a. The NIL Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> NIL</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0000</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The NIL message is used to indicate a message which is to be + ignored when reading the header messages for a data object. + [Possibly one which has been deleted for some reason.] + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> Unspecified</td></tr> +</table></center> +<!-- end msgdesc table --> + + +<h4><a name="DataspaceMessage">IV.A.2.b. The Dataspace Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Dataspace</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0001</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies according to the number of + dimensions, as described in the following table.</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset objects; + may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The dataspace message describes the number of dimensions (in + other words, “rank”) and size of each dimension that + the data object has. This message is only used for datasets which + have a simple, rectilinear, array-like layout; datasets requiring + a more complex layout are not yet supported. + </td> + </tr> + + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Dataspace Message - Version 1 + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4">Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #1<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #n<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Dataspace Message - Version 1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + Dataspace Message. When the format of the + information in the message is changed, the version number + is incremented and can be used to determine how the + information in the object header is formatted. This + document describes version one (1) (there was no version + zero (0)). + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data + object has. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. Bit 1 is used to indicate that + permutation indices are present. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + “<a href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. + If these values are not stored, the maximum size of each + dimension is assumed to be the dimension’s current size. + </p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. If these values are + not stored, the first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + </table> +</div> + + + +<br /> +<p>Version 2 of the dataspace message dropped the optional + permutation index value support, as it was never implemented in the + HDF5 Library:</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Dataspace Message - Version 2 + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Type</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Dataspace Message - Version 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the + Dataspace Message. This field should be ‘2’ for version 2 + format messages. + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data object has. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (the least + significant bit) is used to indicate that maximum + dimensions are present. + </p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of the dataspace: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A <em>scalar</em> dataspace; in other words, + a dataspace with a single, dimensionless element. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A <em>simple</em> dataspace; in other words, + a dataspace with a rank greater than 0 and an + appropriate number of dimensions. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>A <em>null</em> dataspace; in other words, + a dataspace with no elements. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + “<a href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. + If these values are not stored, the maximum size of each + dimension is assumed to be the dimension’s current size. + </p> + </td> + </tr> + + </table> +</div> + + + +<!-- + <h4><a name="DataSpaceMessage">Header Message Name: Complex Dataspace (Fiber Bundle?)</a></h4> + + <!-- start msgdesc table -- + <center> + <table class="msgdesc"> + <p><b>Header Message Name: ???????</b></td></tr> +<b>Header Message Type: </b>0x0002<br /> +<b>Length:</b> Varies</td></tr> + +<b>Status:</b> One of the <em>Simple Dataspace</em> or +<em>Complex Dataspace</em> messages is required (but not both) and may +not be repeated.<br /> <b>Description:</b> The +<em>Dataspace</em> message describes space that the dataset is +mapped onto in a more comprehensive way than the <em>Simple + Dimensionality</em> message is capable of handling. The +dataspace of a dataset encompasses the type of coordinate system +used to locate the dataset’s elements as well as the structure and +regularity of the coordinate system. The dataspace also +describes the number of dimensions which the dataset inhabits as +well as a possible higher dimensional space in which the dataset +is located within. + +<br /> +<p><b>Format of Data:</b></p> + +<center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Message Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Mesh Type</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimensionality</td> + </tr> + </table> +</center> + +<br /> +<dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br /> + The mesh type value is broken up as follows: <br /> + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Mesh-type Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1">Mesh Embedding</td> + <td colspan="1">Coordinate System</td> + <td colspan="1">Structure</td> + <td colspan="1">Regularity</td> + </tr> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset dataspace + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset’s dataspace is located within + another dataspace, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric datatype. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed:</p> + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + dataspace. + <br /> <br /> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Embedded Dimensionality Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Embedded Dimensionality</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #n</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #n</td> + </tr> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located within: in other words, a planar dataset + located within a 3-D space, a 3-D dataset + which is a subset of another 3-D space, and so on. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded dataspace + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset’s + origin within the embedded dataspace. + </dl> +</dl> +[Comment: need some way to handle different orientations of the +dataset dataspace +within the embedded dataspace]<br /> + +<br /> +<center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Regular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Logical Dimension Size #1</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Size #n</td> + </tr> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #n</td> + </tr> + </table> +</center> + +<br /> +<dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> +</dl> +<br /> +<center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Irregular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #n</td> + </tr> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> + </tr> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #n</td> + </tr> + </table> +</center> + +<br /> +<center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Unstructured Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4"># of Grid Points</td> + </tr> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> + </tr> + <tr align="center"> + <td colspan="4">Grid Point Locations<br />.<br />.<br /></td> + </tr> + </table> +</center> +--> + +<h4><a name="LinkInfoMessage">IV.A.2.c. The Link Info Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Link Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x002 </td></tr> + <tr><td colspan="2"><b>Length:</b> Varies </td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated. </td></tr> + <tr><td><b>Description:</b></td> + <td>The link info message tracks variable information about the + current state of the links for a “new style” + group’s behavior. Variable information will be stored in + this message and constant information will be stored in the + <a href="#GroupInfoMessage">Group Info</a> message. + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Link Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Maximum Creation Index <em>(8 bytes, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Name Index<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Creation Order Index<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Link Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field determines various optional aspects of the link + info message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, creation order for the links is tracked. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, creation order for the links is indexed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>This 64-bit value is the maximum creation order index value + stored for a link in this group.</p> + <p>This field is present if bit 0 of <em>flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td> + <p> + This is the address of the fractal heap to store dense links. + Each link stored in the fractal heap is stored as a + <a href="#LinkMessage">Link Message</a>. + </p> + <p> + If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Name Index</p></td> + <td><p>This is the address of the version 2 B-tree to index names of links.</p> + <p>If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Creation Order Index</p></td> + <td><p>This is the address of the version 2 B-tree to index creation order of links.</p> + <p>If there are no links in the group, or the group’s links + are stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + <p>This field exists if bit 1 of <em>flags</em> is set.</p> + </td> + </tr> + + </table> +</div> + + +<h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Datatype</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0003 + </td></tr> + <tr><td colspan="2"><b>Length:</b> Variable</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset or committed + datatype (formerly named datatype) objects; may not be repeated. + </td></tr> + <tr><td><b>Description:</b></td> + <td><p>The datatype message defines the datatype for each element + of a dataset or a common datatype for sharing between multiple + datasets. A datatype can describe an atomic type like a fixed- + or floating-point type or more complex types like a C struct + (compound datatype), array (array datatype), or C++ vector + (variable-length datatype).</p> + <p>Datatype messages that are part of a dataset object do not + describe how elements are related to one another; the dataspace + message is used for that purpose. Datatype messages that are part of + a committed datatype (formerly named datatype) message describe + a common datatype that can be shared by multiple datasets in the + file.</p> + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Datatype Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Class and Version</td> + <td>Class Bit Field, Bits 0-7</td> + <td>Class Bit Field, Bits 8-15</td> + <td>Class Bit Field, Bits 16-23</td> + </tr> + + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br /><br />Properties<br /><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Datatype Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Class and Version</p></td> + <td> + <p>The version of the datatype message and the datatype’s class + information are packed together in this field. The version + number is packed in the top 4 bits of the field and the class + is contained in the bottom 4 bits. + </p> + <p>The version number information is used for changes in the + format of the datatype message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Used by early versions of the library to encode + compound datatypes with explicit array fields. + See the compound datatype description below for + further details. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Used when an array datatype needs to be encoded. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Used when a VAX byte-ordered type needs to be + encoded. Packs various other datatype classes more + efficiently also. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Used to encode the revised reference datatype. + </td> + </tr> + </table></p> + + <p>The class of the datatype determines the format for the class + bit field and properties portion of the datatype message, which + are described below. The + following classes are currently defined: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#ClassFixedPoint">Fixed-Point</a></td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td><a href="#ClassFloatingPoint">Floating-Point</a></td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td> <a href="#ClassTime">Time</a></td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td><a href="#ClassString">String</a></td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td><a href="#ClassBitField">Bit field</a></td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td><a href="#ClassOpaque">Opaque</a></td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td><a href="#ClassCompound">Compound</a></td> + </tr> + + <tr> + <td align="center"><code>7</code></td> + <td><a href="#ClassReference">Reference</a></td> + </tr> + + <tr> + <td align="center"><code>8</code></td> + <td><a href="#ClassEnum">Enumerated</a></td> + </tr> + + <tr> + <td align="center"><code>9</code></td> + <td><a href="#ClassVarLen">Variable-Length</a></td> + </tr> + + <tr> + <td align="center"><code>10</code></td> + <td><a href="#ClassArray">Array</a></td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Class Bit Fields</p></td> + <td> + <p>The information in these bit fields is specific to each datatype + class and is described below. All bits not defined for a + datatype class are set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>The size of a datatype element in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td> + <p>This variable-sized sequence of bytes encodes information + specific to each datatype class and is described for each class + below. If there is no property information specified for a + datatype class, the size of this field is zero bytes. + </p> + </td> + </tr> + + </table> +</div> + + +<br /> +<br /> +<a name="ClassFixedPoint"></a> + <p>Class specific information for the Fixed-point Numbers class + (Class 0):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Fixed-point Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1, 2</p></td> + <td><p><b>Padding type.</b> Bit 1 is the lo_pad bit and bit 2 + is the hi_pad bit. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</p></td> + </tr> + + <tr> + <td><p>3</p></td> + <td><p><b>Signed.</b> If this bit is set then the fixed-point + number is in 2’s complement form.</p></td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Fixed-point Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Fixed-point Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the fixed-point + value within the datatype. The bit offset specifies the number + of bits “to the right of” the value (which are set to the + lo_pad bit value). + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the fixed-point value + within the datatype. This value, combined with the datatype + element’s size and the Bit Offset field specifies the number + of bits “to the left of” the value (which are set to the + hi_pad bit value). + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <a name="ClassFloatingPoint"></a> + <p>Class specific information for the Floating-point Numbers class + (Class 1):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Floating-point Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0, 6</p></td> + <td><p><b>Byte Order.</b> These two non-contiguous bits specify the + “endianness” of the bytes in the datatype element. + <table class="list"> + <tr> + <th width="10%" align="center">Bit 6</th> + <th width="10%" align="center">Bit 0</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td align="center"><code>0</code></td> + <td>Byte order is little-endian + </td> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is big-endian + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td align="center"><code>0</code></td> + <td>Reserved + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is VAX-endian + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>1, 2, 3</p></td> + <td><p><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 + is the high bits pad type, and bit 3 is the internal bits + pad type. If a datum has unused bits at either end or between + the sign bit, exponent, or mantissa, then the value of bit + 1, 2, or 3 is copied to those locations.</p></td> + </tr> + + <tr> + <td><p>4-5</p></td> + <td><p><b>Mantissa Normalization.</b> This 2-bit bit field specifies + how the most significant bit of the mantissa is managed. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>No normalization + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The most significant bit of the mantissa is always set + (except for 0.0). + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The most significant bit of the mantissa is not stored, + but is implied to be set. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Reserved. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>7</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + <tr> + <td><p>8-15</p></td> + <td><p><b>Sign Location.</b> This is the bit position of the sign + bit. Bits are numbered with the least significant bit zero.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Floating-point Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + + <tr> + <td>Exponent Location</td> + <td>Exponent Size</td> + <td>Mantissa Location</td> + <td>Mantissa Size</td> + </tr> + + <tr> + <td colspan="4">Exponent Bias</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Floating-point Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the floating-point + value within the datatype. The bit offset specifies the number + of bits “to the right of” the value. + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the floating-point value + within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Location</p></td> + <td> + <p>The bit position of the exponent field. Bits are numbered with + the least significant bit number zero. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Size</p></td> + <td> + <p>The size of the exponent field in bits. + </p> + </td> + </tr> + + <tr> + <td><p>Mantissa Location</p></td> + <td> + <p>The bit position of the mantissa field. Bits are numbered with + the least significant bit number zero. + </p> + </td> + </tr> + + <tr> + <td><p>Mantissa Size</p></td> + <td> + <p>The size of the mantissa field in bits. + </p> + </td> + </tr> + + <tr> + <td><p>Exponent Bias</p></td> + <td> + <p>The bias of the exponent field. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <a name="ClassTime"></a> + <p>Class specific information for the Time class (Class 2):</p> + + + <div align="center"> + <table class="desc"> + <caption> + Bits: Time Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Time Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Time Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the time value. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <a name="ClassString"></a> + <p>Class specific information for the Strings class (Class 3):</p> + + + <div align="center"> + <table class="desc"> + <caption> + Bits: String Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Padding type.</b> This four-bit value determines the + type of padding to use for the string. The values are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Null Terminate: A zero byte marks the end of the + string and is guaranteed to be present after + converting a long string to a short string. When + converting a short string to a long string the value is + padded with additional null characters as necessary. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Null Pad: Null characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Space Pad: Space characters are added to the end of + the value during conversions from short values to long + values but conversion in the opposite direction simply + truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p><b>Character Set.</b> The character set used to + encode the string. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <p>There are no properties defined for the string class. + </p> + + <br /> + <br /> + <a name="ClassBitField"></a> + <p>Class specific information for the Bit Fields class (Class 4):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Bitfield Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0</p></td> + <td><p><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</p></td> + </tr> + + <tr> + <td><p>1, 2</p></td> + <td><p><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</p></td> + </tr> + + <tr> + <td><p>3-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Bit Field Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Bit Field Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the bit field + within the datatype. The bit offset specifies the number + of bits “to the right of” the value. + </p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the bit field + within the datatype. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <br /> + <a name="ClassOpaque"></a> + <p>Class specific information for the Opaque class (Class 5):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Opaque Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-7</p></td> + <td><p>Length of ASCII tag in bytes.</p></td> + </tr> + + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Opaque Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />ASCII Tag<br /> + <br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Opaque Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>ASCII Tag</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <br /> + <a name="ClassCompound"></a> + <p>Class specific information for the Compound class (Class 6):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Compound Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p><b>Number of Members.</b> This field contains the number + of members defined for the compound datatype. The member + definitions are listed in the Properties field of the data + type message.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + + <p>The Properties field of a compound datatype is a list of the + member definitions of the compound datatype. The member + definitions appear one after another with no intervening bytes. + The member types are described with a (recursively) encoded datatype + message.</p> + + <p>Note that the property descriptions are different for different + versions of the datatype version. Additionally note that the version + 0 datatype encoding is deprecated and has been replaced with later + encodings in versions of the HDF5 Library from the 1.4 release + onward.</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Compound Properties Description for Datatype Version 1 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension Permutation</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #2 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #3 Size (required)</td> + </tr> + + <tr> + <td colspan="4">Dimension #4 Size (required)</td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Compound Properties Description for Datatype Version 1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>If set to zero, this field indicates a scalar member. If set + to a value greater than zero, this field indicates that the + member is an array of values. For array members, the size of + the array is indicated by the ‘Size of Dimension n’ field in + this message. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension Permutation</p></td> + <td> + <p>This field was intended to allow an array field to have + its dimensions permuted, but this was never implemented. + This field should always be set to zero. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This field is the size of a dimension of the array field as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Compound Properties Description for Datatype Version 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Compound Properties Description for Datatype Version 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype. + </p> + </td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Compound Properties Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Member Type Message<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Compound Properties Description for Datatype Version 3 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>This NUL-terminated string provides a description for the + opaque type. It is <em>not</em> NUL-padded to a multiple of 8 + bytes.</p></td> + </tr> + + <tr> + <td><p>Byte Offset of Member</p></td> + <td><p>This is the byte offset of the member within the datatype. + The field size is the minimum number of bytes necessary, + based on the size of the datatype element. For example, a + datatype element size of less than 256 bytes uses a 1 byte + length, a datatype element size of 256-65535 bytes uses a + 2 byte length, and so on.</p></td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td><p>This field is a datatype message describing the datatype of + the member.</p></td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <a name="ClassReference"></a> + <p>Class specific information for the Reference class (Class 7):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Reference Bit Field Description for Datatype Version < 4 + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Type.</b> This four-bit value contains the reference types which are supported for + backward compatibility. The values defined are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Object Reference (H5R_OBJECT1): A reference to another object in this + HDF5 file. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Dataset Region Reference (H5R_DATASET_REGION1): A reference to a region within + a dataset in this HDF5 file. + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Bits: Reference Bit Field Description for Datatype Version 4 + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Type.</b> This four-bit value contains the revised reference types. + The values defined are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Object Reference (H5R_OBJECT2): A reference to another object + in this file or an external file. + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Dataset Region Reference (H5R_DATASET_REGION2): A reference to a region within + a dataset in this file or an external file. + </td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>Attribute Reference (H5R_ATTR): A reference to an attribute attached to an + object in this file or an external file. + </td> + </tr> + + <tr> + <td align="center"><code>5-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p><b>Version.</b> This four-bit value contains the version for encoding + the revised reference types. The values defined are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Unused + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>The version for encoding the revised reference types: Object Reference (2), + Dataset Region Reference (3) and Attribute Reference (4). + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + + </table></p> + + </td> + </tr> + + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <p>There are no properties defined for the reference class. + </p> + + + <br /> + <br /> + <a name="ClassEnum"></a> + <p>Class specific information for the Enumeration class (Class 8):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Enumeration Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p><b>Number of Members.</b> The number of name/value + pairs defined for the enumeration type.</p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Enumeration Property Description for Datatype Versions + 1 and 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Enumeration Property Description for Datatype Versions + 1 and 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually an + integer. The information for that parent type is described + recursively by this field. + </p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p>The name for each name/value pair. Each name is stored as a null + terminated ASCII string in a multiple of eight bytes. The names + are in no particular order. + </p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value + is determined by the parent type. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Enumeration Property Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Enumeration Property Description for Datatype Version 3 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually an + integer. The information for that parent type is described + recursively by this field. + </p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p>The name for each name/value pair. Each name is stored as a null + terminated ASCII string, <em>not</em> padded to a multiple of + eight bytes. The names are in no particular order. + </p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value + is determined by the parent type. + </p> + </td> + </tr> + + </table> + </div> + + + + <br /> + <a name="ClassVarLen"></a> + <p>Class specific information for the Variable-length class (Class 9):</p> + + <div align="center"> + <table class="desc"> + <caption> + Bits: Variable-length Bit Field Description + </caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p><b>Type.</b> This four-bit value contains the type of + variable-length datatype described. The values defined are: + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Sequence: A variable-length sequence of any datatype. + Variable-length sequences do not have padding or + character set information. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>String: A variable-length sequence of characters. + Variable-length strings have padding and character set + information. + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p><b>Padding type.</b> (variable-length string only) + This four-bit value determines the type of padding + used for variable-length strings. The values are the same + as for the string padding type, as follows: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Null terminate: A zero byte marks the end of a string + and is guaranteed to be present after converting a long + string to a short string. When converting a short string + to a long string, the value is padded with additional null + characters as necessary. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Null pad: Null characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Space pad: Space characters are added to the end of the + value during conversion from a short string to a longer + string. Conversion from a long string to a shorter string + simply truncates the value. This is the Fortran + representation of the string. + </td> + </tr> + + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + <p>This value is set to zero for variable-length sequences.</p> + + </td> + </tr> + + <tr> + <td><p>8-11</p></td> + <td><p><b>Character Set.</b> (variable-length string only) + This four-bit value specifies the character set + to be used for encoding the string: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved + </td> + </tr> + </table></p> + + <p>This value is set to zero for variable-length sequences.</p> + + </td> + </tr> + + <tr> + <td><p>12-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Variable-length Property Description + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Variable-length Property Description + </caption> + <tr> + <th width="10%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each variable-length type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <a name="ClassArray"></a> + <p>Class specific information for the Array class (Class 10):</p> + + <p>There are no bit fields defined for the array class. + </p> + + <p>Note that the dimension information defined in the property for this + datatype class is independent of dataspace information for a dataset. + The dimension information here describes the dimensionality of the + information within a data element (or a component of an element, if the + array datatype is nested within another datatype) and the dataspace for a + dataset describes the size and locations of the elements in a dataset. + </p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Array Property Description for Datatype Version 2 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Permutation Index #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Permutation Index #n</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Array Property Description for Datatype Version 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array + as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. Currently, dimension + permutations are not supported, and these indices should + be set to the index position minus one. In other words, + the first dimension should be set to 0, the second dimension + should be set to 1, and so on. + </p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Array Property Description for Datatype Version 3 + </caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Array Property Description for Datatype Version 3 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array + as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The + information for that parent type is described recursively by + this field. + </p> + </td> + </tr> + + </table> + </div> + + + + <h4><a name="OldFillValueMessage">IV.A.2.e. The Data Storage - + Fill Value (Old) Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Fill Value + (old)</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0004</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The fill value message stores a single data value which + is returned to the application when an uninitialized data element + is read from a dataset. The fill value is interpreted with the + same datatype as the dataset. If no fill value message is present + then a fill value of all zero bytes is assumed.</p> + <p>This fill value message is deprecated in favor of the + “new” fill value message (Message Type 0x0005) and + is only written to the file for forward compatibility with + versions of the HDF5 Library before the 1.6.0 version. + Additionally, it only appears for datasets with a user-defined + fill value (as opposed to the library default fill value or an + explicitly set “undefined” fill value).</p> + </td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Layout: Fill Value Message (Old) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Fill Value Message (Old) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. + </p> + </td> + </tr> + </table> + </div> + + + <h4><a name="FillValueMessage">IV.A.2.f. The Data Storage - + Fill Value Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Fill + Value</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0005</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for dataset objects; + may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The fill value message stores a single data value which is + returned to the application when an uninitialized data element + is read from a dataset. The fill value is interpreted with the + same datatype as the dataset.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Layout: Fill Value Message - Versions 1 and 2 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Space Allocation Time</td> + <td>Fill Value Write Time</td> + <td>Fill Value Defined</td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Fill Value Message - Versions 1 and 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Initial version of this message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are + only present if the Fill Value Defined field is set + to 1. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message + more efficiently than version 2. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Space Allocation Time</p></td> + <td> + <p>When the storage space for the dataset’s raw data will be + allocated. The allowed values are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Not used. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Early allocation. Storage space for the entire dataset + should be allocated in the file when the dataset is + created. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Late allocation. Storage space for the entire dataset + should not be allocated until the dataset is written + to. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Incremental allocation. Storage space for the + dataset should not be allocated until the portion + of the dataset is written to. This is currently + used in conjunction with chunked data storage for + datasets. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Fill Value Write Time</p></td> + <td> + <p>At the time that storage space for the dataset’s raw data is + allocated, this value indicates whether the fill value should + be written to the raw data storage elements. The allowed values + are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>On allocation. The fill value is always written to + the raw data storage when the storage space is allocated. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Never. The fill value should never be written to + the raw data storage. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Fill value written if set by user. The fill value + will be written to the raw data storage when the storage + space is allocated only if the user explicitly set + the fill value. If the fill value is the library + default or is undefined, it will not be written to + the raw data storage. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Fill Value Defined</p></td> + <td> + <p>This value indicates if a fill value is defined for this + dataset. If this value is 0, the fill value is undefined. + If this value is 1, a fill value is defined for this dataset. + For version 2 or later of the fill value message, this value + controls the presence of the Size and Fill Value fields. + </p> + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, + and the Fill Value Defined field is set to 0. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is + not present if the Version field is greater than 1, + and the Fill Value Defined field is set to 0. + </p> + </td> + </tr> + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Fill Value Message - Version 3 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Fill Value Message - Version 3 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Initial version of this message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are + only present if the Fill Value Defined field is set + to 1. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message + more efficiently than version 2. + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>When the storage space for the dataset’s raw data will be + allocated. The allowed values are: + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>Space Allocation Time, with the same + values as versions 1 and 2 of the message. + </td> + </tr> + <tr> + <td align="center"><code>2-3</code></td> + <td>Fill Value Write Time, with the same + values as versions 1 and 2 of the message. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Fill Value Undefined, indicating that the fill + value has been marked as “undefined” for this dataset. + Bits 4 and 5 cannot both be set. + </td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>Fill Value Defined, with the same values as + versions 1 and 2 of the message. + Bits 4 and 5 cannot both be set. + </td> + </tr> + <tr> + <td align="center"><code>6-7</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, + and the Fill Value Defined flag is set to 0. + </p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is + not present if the Version field is greater than 1, + and the Fill Value Defined flag is set to 0. + </p> + </td> + </tr> + </table> + </div> + + + <h4><a name="LinkMessage">IV.A.2.g. The Link Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Link</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0006</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies </td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated. </td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message encodes the information for a link in a + group’s object header, when the group is storing its links + “compactly”, or in the group’s fractal heap, + when the group is storing its links “densely”.</p> + <p>A group is storing its links compactly when the fractal heap + address in the <em><a href="#LinkInfoMessage">Link Info + Message</a></em> is set to the “undefined address” + value.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Layout: Link Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td>Link type <em>(optional)</em></td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Creation Order <em>(8 bytes, optional)</em><br /><br /></td> + </tr> + <tr> + <td>Link Name Character Set <em>(optional)</em></td> + <td>Length of Link Name (variable size)</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Link Name (variable size)</td> + </tr> + <tr> + <td colspan="4"><br />Link Information (variable size)<br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Link Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 1.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field contains information about the link and controls + the presence of other fields below. + <table class="list"> + <tr> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>Determines the size of the <em>Length of Link Name</em> + field. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The size of the <em>Length of Link Name</em> + field is 8 bytes. + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Creation Order Field Present: if set, the <em>Creation + Order</em> field is present. If not set, creation order + information is not stored for links in this group. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Link Type Field Present: if set, the link is not + a hard link and the <em>Link Type</em> field is present. + If not set, the link is a hard link. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Link Name Character Set Field Present: if set, the + link name is not represented with the ASCII character + set and the <em>Link Name Character Set</em> field is + present. If not set, the link name is represented with + the ASCII character set. + </td> + </tr> + <tr> + <td align="center"><code>5-7</code></td> + <td>Reserved (zero). + </td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Link type</p></td> + <td><p>This is the link class type and can be one of the following + values: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A hard link (should never be stored in the file) + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A soft link. + </td> + </tr> + <tr> + <td align="center"><code>2-63</code></td> + <td>Reserved for future HDF5 internal use. + </td> + </tr> + <tr> + <td align="center"><code>64</code></td> + <td>An external link. + </td> + </tr> + <tr> + <td align="center"><code>65-255</code></td> + <td>Reserved, but available for user-defined link types. + </td> + </tr> + </table></p> + + <p>This field is present if bit 3 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Creation Order</p></td> + <td><p>This 64-bit value is an index of the link’s creation time within + the group. Values start at 0 when the group is created an increment + by one for each link added to the group. Removing a link from a + group does not change existing links’ creation order field. + </p> + <p>This field is present if bit 2 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Link Name Character Set</p></td> + <td><p>This is the character set for encoding the link’s name: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding (this should never be stored + in the file) + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + </table></p> + + <p>This field is present if bit 4 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Length of link name</p></td> + <td><p>This is the length of the link’s name. The size of this field + depends on bits 0 and 1 of <em>Flags</em>.</p> + </td> + </tr> + + <tr> + <td><p>Link name</p></td> + <td><p>This is the name of the link, non-NULL terminated.</p> + </td> + </tr> + + <tr> + <td><p>Link information</p></td> + <td><p>The format of this field depends on the <em>link type</em>.</p> + <p>For <b>hard</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%"><i><a href="#SizeOfOffsetsV0"> + Size of Offsets</a></i> bytes:</td> + <td width="80%">The address of the object header for the object that the + link points to. + </td> + </tr> + </table> + </p> + + <p> + For <b>soft</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of soft link value.</td> + </tr> + <tr> + <td><em>Length of soft link value</em> bytes:</td> + <td>A non-NULL-terminated string storing the value of the + soft link. + </td> + </tr> + </table> + </p> + + <p> + For <b>external</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of external link value.</td> + </tr> + <tr> + <td><em>Length of external link value</em> bytes:</td> + <td>The first byte contains the version number in the + upper 4 bits and flags in the lower 4 bits for the external + link. Both version and flags are defined to be zero in + this document. The remaining bytes consist of two + NULL-terminated strings, with no padding between them. + The first string is the name of the HDF5 file containing + the object linked to and the second string is the full path + to the object linked to, within the HDF5 file’s + group hierarchy. + </td> + </tr> + </table> + </p> + + <p> + For <b>user-defined</b> links, the field is formatted as follows: + + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of user-defined data.</td> + </tr> + <tr> + <td><em>Length of user-defined link value</em> bytes:</td> + <td>The data supplied for the user-defined link type.</td> + </tr> + </table> + </p> + + </td> + </tr> + </table> + </div> + + <h4><a name="ExternalFileListMessage">IV.A.2.h. The Data Storage - + External Data Files Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> External + Data Files</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0007</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The external data storage message indicates that the data + for an object is stored outside the HDF5 file. The filename of + the object is stored as a Universal Resource Location (URL) of + the actual filename containing the data. An external file list + record also contains the byte offset of the start of the data + within the file and the amount of space reserved in the file + for that data.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Layout: External File List Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="2">Allocated Slots</td> + <td colspan="2">Used Slots</td> + </tr> + + <tr> + <td colspan="4"><br />Heap Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Slot Definitions...<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: External File List Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of + External Data Storage Message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The current version used by the library.</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Allocated Slots</p></td> + <td> + <p>The total number of slots allocated in the message. Its value must be at least as + large as the value contained in the Used Slots field. (The current library simply + uses the number of Used Slots for this message)</p> + </td> + </tr> + + <tr> + <td><p>Used Slots</p></td> + <td> + <p>The number of initial slots which contains valid information.</p> + </td> + </tr> + + <tr> + <td><p>Heap Address</p></td> + <td> + <p>This is the address of a local heap which contains the names for the external + files (The local heap information can be found in Disk Format Level 1D in this + document). The name at offset zero in the heap is always the empty string.</p> + </td> + </tr> + + <tr> + <td><p>Slot Definitions</p></td> + <td> + <p>The slot definitions are stored in order according to the array addresses they + represent.</p> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: External File List Slot + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name Offset in Local Heap<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset in External Data File<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Size in External File<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: External File List Slot + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name Offset in Local Heap</p></td> + <td> + <p>The byte offset within the local name heap for the name + of the file. File names are stored as a URL which has a + protocol name, a host name, a port number, and a file + name: + <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. + If the protocol is omitted then “file:” is assumed. If + the port number is omitted then a default port for that + protocol is used. If both the protocol and the port + number are omitted then the colon can also be omitted. If + the double slash and host name are omitted then + “localhost” is assumed. The file name is the only + mandatory part, and if the leading slash is missing then + it is relative to the application’s current working + directory (the use of relative names is not + recommended). + </p> + </td> + </tr> + + <tr> + <td><p>Offset in External Data File</p></td> + <td> + <p>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single + dataset this will usually be zero.</p> + </td> + </tr> + + <tr> + <td><p>Data Size in External File</p></td> + <td> + <p>This is the total number of bytes reserved in the + specified file for raw data storage. For a file that + contains exactly one complete dataset which is not + extendable, the size will usually be the exact size of the + dataset. However, by making the size larger one allows + HDF5 to extend the dataset. The size can be set to a value + larger than the entire file since HDF5 will read zeroes + past the end of the file without failing.</p> + </td> + </tr> + </table> + </div> + + + <h4><a name="LayoutMessage">IV.A.2.i. The Data Layout Message</a></h4> + + <!-- start msgdesc table --> + <center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Data Layout</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0008</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for datasets; may not + be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The Data Layout message + describes how the elements of a multi-dimensional array are stored + in the HDF5 file. Four types of data layout are supported: + <ol> + <li>Contiguous: The array is stored in one contiguous area of + the file. This layout requires that the size of the array be + constant: data manipulations such as chunking, compression, + checksums, or encryption are not permitted. The message stores + the total storage size of the array. The offset of an element + from the beginning of the storage area is computed as in a C + array.</li> + <li>Chunked: The array domain is regularly decomposed into + chunks, and each chunk is allocated and stored separately. This + layout supports arbitrary element traversals, compression, + encryption, and checksums (these features are described + in other messages). The message stores the size of a chunk + instead of the size of the entire array; the storage size of + the entire array can be calculated by traversing the chunk index + that stores the chunk addresses.</li> + <li>Compact: The array is stored in one contiguous block as + part of this object header message.</li> + <li>Virtual: This is only supported for version 4 of the Data + Layout message. The message stores information that is used to + locate the global heap collection containing the Virtual Dataset + (VDS) mapping information. The mapping associates the VDS to + the source dataset elements that are stored across a collection + of HDF5 files.</li> + </ol></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> + </table></center> + <!-- end msgdesc table --> + + <div align="center"> + <table class="format"> + <caption> + Layout: Data Layout Message (Versions 1 and 2) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Layout Class</td> + <td>Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Data Address<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> + + <tr> + <td colspan="4">Dimension 2 Size</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Dataset Element Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Compact Data Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Compact Data... <em>(variable size, optional)</em><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Data Layout Message (Versions 1 and 2) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of the data + layout message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by version 1.4 and before of the library to encode layout information. + Data space is always allocated when the data set is created.</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by version 1.6.[0,1,2] of the library to encode layout information. + Data space is allocated only when it is necessary.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the + message. The value stored for chunked storage is 1 greater than + the number of dimensions in the dataset’s dataspace. + For example, 2 is stored for a 1 dimensional dataset. + </p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for the data + and how the other fields of the layout message are to be + interpreted. + + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Data Address</p></td> + <td><p>For contiguous storage, this is the address of the raw + data in the file. For chunked storage this is the address + of the <a href="#V1Btrees">v1 B-tree</a> that is used to look up the addresses of the + chunks. This field is not present for compact storage. + If the version for this message is greater than 1, the address + may have the “undefined address” value, to indicate that + storage has not yet been allocated for this array.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>For contiguous and compact storage the dimensions define + the entire size of the array while for chunked storage they define + the size of a single chunk. In all cases, they are in units of + array elements (not bytes). The first dimension stored in the list + of dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes. This field is only + present for chunked storage. + </p> + </td> + </tr> + + <tr> + <td><p>Compact Data Size</p></td> + <td><p>This field is only present for compact data storage. + It contains the size of the raw data for the dataset array, in + bytes.</p> + </td> + </tr> + + <tr> + <td><p>Compact Data</p></td> + <td><p>This field is only present for compact data storage. + It contains the raw data for the dataset array.</p> + </td> + </tr> + </table> + </div> + + <br /> + <p>Version 3 of this message re-structured the format into specific + properties that are required for each layout class.</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Data Layout Message (Version 3) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Layout Class</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Properties <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Data Layout Message (Version 3) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the format of layout message + and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the version 1.6.3 and later of the library to store properties + for each layout class.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for the data + and how the other fields of the layout message are to be + interpreted. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td><p>This variable-sized field encodes information specific to each + layout class and is described below. If there is no property + information specified for a layout class, the size of this field + is zero bytes.</p></td> + </tr> + </table> + </div> + + <br /> + <a name="CompactStorage"></a> + <p>Class-specific information for compact storage (layout class 0): (Note: The dimensionality information + is in the Dataspace message)</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Compact Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Raw Data... <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Compact Storage Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size of the raw data for the dataset + array, in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Raw Data</p></td> + <td><p>This field contains the raw data for the dataset array.</p></td> + </tr> + </table> + </div> + + + <br /> + <a name="ContiguousStorage"></a> + <p>Class-specific information for contiguous storage (layout class 1): + (Note: The dimensionality information is in the Dataspace message)</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Contiguous Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Contiguous Storage Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the raw data in the file. + The address may have the “undefined address” value, to indicate + that storage has not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size allocated to store the raw data, + in bytes. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + <p>Class-specific information for chunked storage (layout class 2):</p> + + + <div align="center"> + <table class="format"> + <caption> + Layout: Chunked Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Dimension 0 Size</td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Dataset Element Size</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Chunked Storage Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>A chunk has a fixed dimensionality. This field specifies + the number of dimension size fields later in the message.</p></td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the <a href="#V1Btrees">v1 B-tree</a> + that is used to look up the + addresses of the chunks that actually store portions of the array + data. The address may have the “undefined address” value, to + indicate that storage has not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>These values define the dimension size of a single chunk, in + units of array elements (not bytes). The first dimension stored in + the list of dimensions is the slowest changing dimension and the + last dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes. + </p> + </td> + </tr> + </table> + </div> + + + <br /> + + <p><a name="DataLayoutV4"> + Version 4</a> of this message is similar to version 3 but has + additional information for the virtual layout class as well as + indexing information for the chunked layout class.</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: Data Layout Message (Version 4) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Layout Class</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Properties <em>(variable size)</em><br /><br /></td> + </tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Data Layout Message (Version 4) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The value for this field is 4 and is used by version 1.10.0 + and later of the library to store properties for each layout + class and indexing information for the chunked layout. + </p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for the data + and how the other fields of the layout message are to be + interpreted. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Virtual Storage + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td><p>This variable-sized field encodes information specific to a + layout class as follows: + <table class="list"> + <tr> + <th align="left" width="20%">Layout Class</th> + <th align="left" width="80%">Description</th> + </tr> + + <tr> + <td align="left">Compact Storage</td> + <td>See <a href="#CompactStorage">Compact Storage + Property Description</i></a> for the version 3 +Data Layout message. +</td> +</tr> + +<tr> + <td align="left">Contiguous Storage</td> + <td>See <a href="#ContiguousStorage">Contiguous Storage + Property Description</i></a> for the version 3 +Data Layout message. +</td> +</tr> + +<tr> + <td align="left">Chunked Storage</td> + <td>See <a href="#ChunkedStorage">Chunked Storage + Property Description</i></a> below. +</td> +</tr> + +<tr> + <td align="left">Virtual Storage</td> + <td>See <a href="#VirtualStorage">Virtual Storage + Property Description</i></a> below. +</td> +</tr> +</table> + +</p></td> +</tr> +</table> +</div> + +<br /> +<a name="ChunkedStorage"></a> +<p>Class-specific information for chunked storage (layout + class 2):</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Chunked Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Flags</td> + <td>Dimensionality</td> + <td>Dimension Size Encoded Length</td> + <td colspan="1" bgcolor="#DDDDDD"><em>This space inserted to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Dimension 0 Size <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size <em>(variable size)</em></td> + </tr> + + <tr> + <td>Chunk Indexing Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Indexing Type Information <em>(variable size)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Chunked Storage Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the chunked layout feature flag:</p> + + <table class="list"> + <tr> + <th width="55%" align="left">Value</th> + <th width="45%" align="left">Description</th> + </tr> + + <tr> + <td align="left"><code>DONT_FILTER_PARTIAL_BOUND_CHUNKS (bit 0)</code></td> + <td>Do not apply filter to a partial edge chunk. + + </td> + </tr> + + <tr> + <td align="left"><code>SINGLE_INDEX_WITH_FILTER (bit 1)</code></td> + <td>A filtered chunk for <i>Single Chunk</i> indexing. + </td> + </tr> + + </table> + + </td> + + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>A chunk has fixed dimension. This field specifies + the number of <em>Dimension Size</em> fields later in the message.</p></td> + </tr> + + <tr> + <td><p>Dimension Size Encoded Length</p></td> + <td> + <p>This is the size in bytes used to encode <em>Dimension Size</em>. + </p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>These values define the dimension size of a single chunk, in + units of array elements (not bytes). The first dimension stored in + the list of dimensions is the slowest changing dimension and the + last dimension stored is the fastest changing dimension. + </p> + </td> + </tr> + + <tr> + <td><p>Chunk Indexing Type</p></td> + <td><p>There are five indexing types used to look up addresses + of the chunks. For more information on each type, see + <a href="#AppendixC">“Appendix C: Types of Indexes for + Dataset Chunks.”</a> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td><a href="#SingleChunk"><i>Single Chunk</i></a> indexing type. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td><a href="#Implicit"><i>Implicit</i></a> indexing type. + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td><a href="#FixedArray"><i>Fixed Array</i></a> indexing type. + </td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td><a href="#ExtensibleArray"><i>Extensible Array</i></a> indexing type. + </td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td><a href="#V2Btrees"><i>Version 2 B-tree</i></a> indexing type. + </td> + </tr> + + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Indexing Type Information</p></td> + <td><p>This variable-sized field encodes information specific to + an indexing type. More information on what is encoded with + each type can be found below this table. + <ul> + <li>See <a href="#IndexInfoSingle"><i>Single Chunk</i></a> below.</li> + <li>See <a href="#IndexInfoImplicit"><i>Implicit</i></a> below.</li> + <li>See <a href="#IndexInfoFixed"><i>Fixed Array</i></a> below.</li> + <li>See <a href="#IndexInfoExtensible"><i>Extensible Array</i></a> below.</li> + <li>See <a href="#IndexInfoV2Btrees"><i>Version 2 B-tree</i></a> below.</li> + </ul> + </p> + </td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address specific to an indexing type. + The address may be undefined if the chunk or index storage is not allocated yet. + <table class="list"> + <tr> + <th width="40%" align="left">Value</th> + <th width="60%" align="left">Description</th> + </tr> + + <tr> + <td align="left"><i>Single Chunk index</i></td> + <td align="left">Address of the single chunk.</td> + </td> + </tr> + + <tr> + <td align="left"><i>Implicit index</i></td> + <td align="left">Address of the array of dataset chunks.</td> +</td> +</tr> + +<tr> + <td align="left"><i>Fixed Array index</i></td> + <td align="left">Address of the index.</td> +</tr> + +<tr> + <td align="left"><i>Extensible Array index</i></td> + <td align="left">Address of the index.</td> +</td> +</tr> + +<tr> + <td align="left"><i>Version 2 B-tree index</i></td> + <td align="left">Address of the index.</td> +</td> +</tr> + +</table> + +</p> +</td> +</tr> + +</table> +</div> + +<br /> + +<ol> + <li> + <a name="IndexInfoSingle"></a> + Index-specific information for <i>Single Chunk</i>: + </li> + + <p>The following information exists only when the chunk is filtered. + In other words, when <code>DONT_FILTER_PARTIAL_BOUND_CHUNKS</code> + (bit 0) is enabled in the field <em>flags</em>.</p> + + <div align="center"> + <table class="format"> + <caption> + Layout: Single Chunk Indexing Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Size of filtered chunk<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filters for chunk</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="55%"> </td> + <td width="45%"> <!-- width is slightly different: these + tables are part of an ordered list; see <ol> tags. --> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Single Chunk Indexing Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size of filtered chunk</p></td> + <td><p>This field is the size of a filtered chunk.</p></td> + </tr> + + <tr> + <td><p>Filters for chunk</p></td> + <td><p>This field contains filters for the chunk.</p></td> + </tr> + </table> + </div> +</p> + +<br /> + +<li> + <a name="IndexInfoImplicit"></a> + Index-specific information for <i>Implicit</i>: +</li> + +<div align="center"> + <table class="format"> + <caption> + Layout: Implicit Indexing Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4" bgcolor="#DDDDDD"> + <em>No specific indexing information</em></td> + </tr> + + </table> +</div> + +<br /> +<li> + <a name="IndexInfoFixed"></a> + Index-specific information for <i>Fixed Array</i>: +</li> + +<div align="center"> + <table class="format"> + <caption> + Layout: Fixed Array Indexing Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="1">Page Bits</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fixed Array Indexing Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Page Bits</p></td> + <td><p>This field contains the number of bits needed to store the + maximum number of elements in a data block page.</p></td> + </tr> + + </table> +</div> +</p> + +<br /> +<li> + <a name="IndexInfoExtensible"></a> + Index-specific information for <i>Extensible Array</i>: +</li> + +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Indexing Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Max Bits</td> + <td>Index Elements</td> + <td>Min Pointers</td> + <td>Min Elements</td> + </tr> + + <td colspan="2">Page Bits</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> +</tr> + +</table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Indexing Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Max Bits</p></td> + <td><p>This field contains the number of bits needed to store the maximum number of elements + in the array. + </p> + </td> + </tr> + + <tr> + <td><p>Index Elements</p></td> + <td><p>This field contains the number of elements to store in the + index block. + </p> + </td> + </tr> + + <tr> + <td><p>Min Pointers</p></td> + <td><p>This field contains the minimum number of data block pointers + for a superblock. + </p> + </td> + </tr> + + <tr> + <td><p>Min Elements</p></td> + <td><p>This field contains the minimum number of elements per data block. + </p> + </td> + </tr> + + <tr> + <td><p>Page Bits</p></td> + <td><p>This field contains the number of bits needed to store the + maximum number of elements in a data block page. + </p> + </td> + </tr> + + </table> +</div> +</p> +<br /> + +<li> + <a name="IndexInfoV2Btrees"></a> + Index-specific information for <i>Version 2 B-tree</i>: +</li> + +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 B-tree Indexing Information + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Node Size</td> + </tr> + + <tr> + <td>Split Percent</td> + <td>Merge Percent</td> + <td colspan="2" bgcolor="#DDDDDD"> + <em>This space inserted only to align table nicely</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 B-tree Indexing Information + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Node Size</p></td> + <td><p>This field is the size in bytes of a B-tree node. + </p> + </td> + </tr> + + <tr> + <td><p>Split Percent</p></td> + <td><p>This field is the percentage full of a B-tree node at which to split the node.</p></td> + </tr> + + <tr> + <td><p>Merge Percent</p></td> + <td><p>This field is the percentage full of a B-tree node at which to merge the node.</p></td> + </tr> + </table> +</div> +</ol> + + + +<br /> +<a name="VirtualStorage"></a> +<p> + Class-specific information for virtual storage (layout class 3):</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Virtual Storage Property Description + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Index</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Virtual Storage Property Description + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the global heap collection where + the VDS mapping entries are stored. + See <a href="#GlobalHeapVDS">“Disk Format: Level 1F - + Global Heap Block for Virtual Datasets.”</a> + </p></td> + </tr> + + <tr> + <td><p>Index</p></td> + <td><p>This is the index of the data object within the global heap collection. + </p> + </td> + </tr> + </table> +</div> + +<h4><a name="BogusMessage">IV.A.2.j. The Bogus Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Bogus</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0009</td></tr> + <tr><td colspan="2"><b>Length:</b> 4 bytes</td></tr> + <tr><td colspan="2"><b>Status:</b> For testing only; should never + be stored in a valid file.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message is used for testing the HDF5 Library’s + response to an “unknown” message type and should + never be encountered in a valid HDF5 file.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Bogus Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Bogus Value</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Bogus Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bogus Value</p></td> + <td> + <p>This value should always be: <code>0xdeadbeef</code>.</p> + </td> + </tr> + </table> +</div> + +<h4><a name="GroupInfoMessage">IV.A.2.k. The Group Info Message +</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Group Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000A</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message stores information for the constants defining + a “new style” group’s behavior. Constant + information will be stored in this message and variable + information will be stored in the + <a href="#LinkInfoMessage">Link Info</a> message.</p> + <p>Note: the “estimated entry” information below is + used when determining the size of the object header for the + group when it is created.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Group Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Link Phase Change: Maximum Compact Value <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Link Phase Change: Minimum Dense Value <em>(optional)</em></td> + <td colspan="2">Estimated Number of Entries <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Estimated Link Name Length of Entries <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Group Info Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the group information flag with the following definition: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, link phase change values are stored. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the estimated entry information is non-default + and is stored. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Link Phase Change: Maximum Compact Value</p></td> + <td><p>The is the maximum number of links to store “compactly” (in + the group’s object header).</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Link Phase Change: Minimum Dense Value</p></td> + <td><p>This is the minimum number of links to store “densely” (in + the group’s fractal heap). The fractal heap’s address is + located in the <a href="#LinkInfoMessage">Link Info</a> + message.</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Estimated Number of Entries</p></td> + <td><p>This is the estimated number of entries in groups.</p> + <p>If this field is not present, the default value of <code>4</code> + will be used for the estimated number of group entries.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Estimated Link Name Length of Entries</p></td> + <td><p>This is the estimated length of entry name.</p> + <p>If this field is not present, the default value of <code>8</code> + will be used for the estimated link name length of group entries.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + </table> +</div> +<!-- </p> --> + +<h4><a name="FilterMessage">IV.A.2.l. The Data Storage - Filter + Pipeline Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> + Data Storage - Filter Pipeline</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000B</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>This message describes the filter pipeline which should + be applied to the data stream by providing filter identification + numbers, flags, a name, and client data.</p> + <p>This message may be present in the object headers of both + dataset and group objects. For datasets, it specifies the + filters to apply to raw data. For groups, it specifies the + filters to apply to the group’s fractal heap. Currently, + only datasets using chunked data storage use the filter + pipeline on their raw data.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Filter Pipeline Message - Version 1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Filter Pipeline Message - Version 1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 1.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a + message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Filter Description - Version 1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length</td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Padding <em>(variable size, optional)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Filter Description - Version 1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, + is designed to be a unique identifier for the filter. + Values from zero through 32,767 are reserved for filters + supported by The HDF Group in the HDF5 Library and for + filters requested and supported by third parties. + Filters supported by The HDF Group are documented immediately + below. Information on 3rd-party filters can be found at + The HDF Group’s + <a href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page.</p> + + <p> + To request a filter identifier, please contact + The HDF Group’s Help Desk at + <img src="Graphics/help.png" valign="middle" height="14" + alt="The HDF Group Help Desk">. + You will be asked to provide the following information:</p> + <ol> + <li>Contact information for the developer requesting the + new identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p> + Values from 32768 to 65535 are reserved for non-distributed uses + (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p> + The filters currently in library version 1.8.0 are + listed below: + + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + </p></td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. The + bit values defined so far are: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently skipped in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p>Each filter can store integer values to control + how the filter operates. The number of entries in the + <em>Client Data</em> array is stored in this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>If the <em>Name Length</em> field is non-zero then it will + contain the size of this field, padded to a multiple of eight. This + field contains a null-terminated, ASCII character string to serve + as a comment/name for the filter.</p></td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p>This is an array of four-byte integers which will be + passed to the filter function. The <em>Client Data Number</em> of + Values determines the number of elements in the array.</p></td> + </tr> + + <tr> + <td><p>Padding</p></td> + <td><p>Four bytes of zeroes are added to the message at this + point if the Client Data Number of Values field contains + an odd number.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Filter Pipeline Message - Version 2 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Filter Pipeline Message - Version 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 2.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a + message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Filter Description - Version 2 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Filter Description - Version 2 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, + is designed to be a unique identifier for the filter. + Values from zero through 32,767 are reserved for filters + supported by The HDF Group in the HDF5 Library and for + filters requested and supported by third parties. + Filters supported by The HDF Group are documented immediately + below. Information on 3rd-party filters can be found at + The HDF Group’s + <a href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page.</p> + + <p> + To request a filter identifier, please contact + The HDF Group’s Help Desk at + <img src="Graphics/help.png" valign="middle" height="14" + alt="The HDF Group Help Desk">. + You will be asked to provide the following information:</p> + <ol> + <li>Contact information for the developer requesting the + new identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p> + Values from 32768 to 65535 are reserved for non-distributed uses + (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p> + The filters currently in library version 1.8.0 are + listed below: + + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + </p></td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII name + and this field holds the length of the name including the + null termination padded with nulls to be a multiple of + eight. If the filter has no name then a value of zero is + stored in this field.</p> + <p>Filters with IDs less than 256 (in other words, filters + that are defined in this format documentation) do not store + the <em>Name Length</em> or <em>Name</em> fields. + </p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. The + bit values defined so far are: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. + During output, if an optional filter fails it will be + silently skipped in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p>Each filter can store integer values to control + how the filter operates. The number of entries in the + <em>Client Data</em> array is stored in this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>If the <em>Name Length</em> field is non-zero, then it will + contain the size of this field, <em>not</em> padded to a multiple + of eight. This field contains a <em>non-</em>null-terminated, + ASCII character string to serve as a comment/name for the filter. + </p> + <p>Filters that are defined in this format documentation + such as deflate and shuffle do not store the <em>Name + Length</em> or <em>Name</em> fields. + </p> + </td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p>This is an array of four-byte integers which will be + passed to the filter function. The Client Data Number of + Values</em> determines the number of elements in the array.</p> +</td> +</tr> +</table> +</div> + +<h4><a name="AttributeMessage">IV.A.2.m. The Attribute Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Attribute</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000C</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The <em>Attribute</em> message is used to store objects + in the HDF5 file which are used as attributes, or + “metadata” about the current object. An attribute + is a small dataset; it has a name, a datatype, a dataspace, and + raw data. Since attributes are stored in the object header, they + should be relatively small (in other words, less than 64KB). + They can be associated with any type of object which has an + object header (groups, datasets, or committed (named) + 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"> + “Special Issues”</a> section of the Attributes chapter + in the <cite>HDF5 User’s 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. + Attributes on different objects may have the same name, + however.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Attribute Message (Version 1) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Attribute Message (Version 1) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the format of the + attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6 to encode attribute message. + This version does not support shared datatypes.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator. Note that the <em>Name</em> field below may + contain additional padding not represented by this + field.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below. Note that the <em>Datatype</em> field may contain + additional padding not represented by this field.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below. Note that the <em>Dataspace</em> field may contain + additional padding not represented by this field.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is + padded with additional null characters to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. This + field is padded with additional zero bytes to make it a + multiple of eight bytes.</p></td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. This + field is <em>not</em> padded with additional bytes.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Attribute Message (Version 2) + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Attribute Message (Version 2) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the + format of the attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.x and after to encode + attribute messages. + This version supports shared datatypes. The fields of + name, datatype, and dataspace are not padded with + additional bytes of zero. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s datatype is + shared, this field will contain a “shared message” encoding + instead of the datatype encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s dataspace is + shared, this field will contain a “shared message” encoding + instead of the dataspace encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes.</p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. + </p> + <p>This field is <em>not</em> padded with additional zero bytes. + </p> + </td> + </tr> + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Attribute Message (Version 3) + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td>Name Character Set Encoding</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Attribute Message (Version 3) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in the + format of the attribute message and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8.x and after to + encode attribute messages. + This version supports attributes with non-ASCII names. + </td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including the + null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p>The length of the datatype description in the <em>Datatype</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p>The length of the dataspace description in the <em>Dataspace</em> + field below.</p></td> + </tr> + + <tr> + <td><p>Name Character Set Encoding</p></td> + <td><p>The character set encoding for the attribute’s name: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s datatype is + shared, this field will contain a “shared message” encoding + instead of the datatype encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. + </p> + <p>If the + <em>Flag</em> field indicates this attribute’s dataspace is + shared, this field will contain a “shared message” encoding + instead of the dataspace encoding. + </p> + <p>This field is <em>not</em> padded with additional bytes.</p> + </td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is determined + from the datatype and dataspace descriptions. + </p> + <p>This field is <em>not</em> padded with additional zero bytes. + </p> + </td> + </tr> + </table> +</div> + +<h4><a name="CommentMessage">IV.A.2.n. The Object Comment + Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Comment</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000D</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object comment is designed to be a short description of + an object. An object comment is a sequence of non-zero + (<code>\0</code>) ASCII characters with no other formatting + included by the library.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Object Comment Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Comment <em>(variable size)</em><br /><br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Object Comment Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>A null terminated ASCII character string.</p></td> + </tr> + </table> +</div> + +<h4><a name="OldModificationTimeMessage">IV.A.2.o. The Object + Modification Time (Old) Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Modification Time (Old)</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000E</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td><p>The object modification date and time is a timestamp + which indicates (using ISO-8601 date and time format) the last + modification of an object. The time is updated when any object + header message changes according to the system clock where the + change was posted. All fields of this message should be + interpreted as coordinated universal time (UTC).</p> + <p>This modification time message is deprecated in favor of + the “new” <a href="#ModificationTimeMessage">Object + Modification Time</a> message and is no longer written to the + file in versions of the HDF5 Library after the 1.6.0 + version.</p></td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Modification Time Message (Old) + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Year</td> + </tr> + + <tr> + <td colspan="2">Month</td> + <td colspan="2">Day of Month</td> + </tr> + + <tr> + <td colspan="2">Hour</td> + <td colspan="2">Minute</td> + </tr> + + <tr> + <td colspan="2">Second</td> + <td colspan="2">Reserved</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Modification Time Message (Old) + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Year</p></td> + <td><p>The four-digit year as an ASCII string. For example, + <code>1998</code>. + </p></td> + </tr> + + <tr> + <td><p>Month</p></td> + <td><p>The month number as a two digit ASCII string where + January is <code>01</code> and December is <code>12</code>.</p></td> + </tr> + + <tr> + <td><p>Day of Month</p></td> + <td><p>The day number within the month as a two digit ASCII + string. The first day of the month is <code>01</code>.</p></td> + </tr> + + <tr> + <td><p>Hour</p></td> + <td><p>The hour of the day as a two digit ASCII string where + midnight is <code>00</code> and 11:00pm is <code>23</code>.</p></td> + </tr> + + <tr> + <td><p>Minute</p></td> + <td><p>The minute of the hour as a two digit ASCII string where + the first minute of the hour is <code>00</code> and + the last is <code>59</code>.</p></td> + </tr> + + <tr> + <td><p>Second</p></td> + <td><p>The second of the minute as a two digit ASCII string + where the first second of the minute is <code>00</code> + and the last is <code>59</code>.</p></td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td><p>This field is reserved and should always be zero.</p></td> + </tr> + </table> +</div> + +<h4><a name="SOHMTableMessage">IV.A.2.p. The Shared Message Table + Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Shared Message + Table</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x000F</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message is used to locate the table of shared object + header message (SOHM) indexes. Each index consists of information + to find the shared messages from either the heap or object header. + This message is <em>only</em> found in the superblock + extension.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Shared Message Table Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Shared Object Header Message Table Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td>Number of Indices</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + </table> + + <table class="note"> + <tr> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Shared Message Table Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes version 0.</p></td> + </tr> + + <tr> + <td><p>Shared Object Header Message Table Address</p></td> + <td><p>This field is the address of the master table for shared + object header message indexes.</p> + </td> + </tr> + + <tr> + <td><p>Number of Indices</p></td> + <td><p>This field is the number of indices in the master table. + </p></td> + </tr> + + </table> +</div> + +<h4><a name="ContinuationMessage">IV.A.2.q. The Object Header + Continuation Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object Header + Continuation</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0010</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object header continuation is the location in the file + of a block containing more header messages for the current data + object. This can be used when header blocks become too large or + are likely to change over time.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Object Header Continuation Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Offset<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Length<sup>L</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Object Header Continuation Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Offset</p></td> + <td><p>This value is the address in the file where the + header continuation block is located.</p></td> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>This value is the length in bytes of the header continuation + block in the file.</p></td> + </tr> + </table> +</div> +<br /> + +<p>The format of the header continuation block that this message points + to depends on the version of the object header that the message is + contained within. +</p> + +<p> + Continuation blocks for version 1 object headers have no special + formatting information; they are merely a list of object header + message info sequences (type, size, flags, reserved bytes and data + for each message sequence). See the description + of <a href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix.</a> +</p> + +<p>Continuation blocks for version 2 object headers <em>do</em> have + special formatting information as described here + (see also the description of + <a href="#V2ObjectHeaderPrefix">Version 2 Data Object Header Prefix.</a>): +</p> +<div align="center"> + <table class="format"> + <caption> + Layout: Version 2 Object Header Continuation Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /><br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /><br /></td> + </tr> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 Object Header Continuation Block + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>OCHK</code>” + is used to indicate the beginning of an object header + continuation block. This gives file consistency checking + utilities a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in.</p> + <p>This field is present if bit 2 of <em>flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described above. + </p></td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an + object header message prefix (message type + message size + + message flags).</p> + <p>Gaps are formed when a message (typically an attribute message) + in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved + into the earlier chunk.</p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk. + </p> + </td> + </tr> + </table> +</div> + +<h4><a name="SymbolTableMessage">IV.A.2.r. The Symbol Table + Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Symbol Table + Message</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0011</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Required for + “old style” groups; may not be repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>Each “old style” group has a v1 B-tree and a + local heap for storing symbol table entries, which are located + with this message.</td></tr> + <tr><td colspan="2"><b>Format of data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Symbol Table Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />v1 B-tree Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Local Heap Address<sup>O</sup><br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Symbol Table Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>v1 B-tree Address</p></td> + <td><p>This value is the address of the v1 B-tree containing the + symbol table entries for the group.</p></td> + </tr> + + <tr> + <td><p>Local Heap Address</p></td> + <td><p>This value is the address of the local heap containing + the link names for the symbol table entries for the group.</p></td> + </tr> + </table> +</div> + +<h4><a name="ModificationTimeMessage">IV.A.2.s. The Object + Modification Time Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object + Modification Time</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0012</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>The object modification time is a timestamp which indicates + the time of the last modification of an object. The time is + updated when any object header message changes according to + the system clock where the change was posted.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Modification Time Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4">Seconds After UNIX Epoch</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Modification Time Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used for changes in the format of Object Modification Time + and is described here: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by Version 1.6.1 and after of the library to encode time. In + this version, the time is the seconds after Epoch.</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Seconds After UNIX Epoch</p></td> + <td><p>A 32-bit unsigned integer value that stores the number of + seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, + Coordinated Universal Time.</p></td> + </tr> + </table> +</div> + +<h4><a name="BtreeKValuesMessage">IV.A.2.t. The B-tree + ‘K’ Values Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> B-tree + ‘K’ Values</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0013</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message retrieves non-default ‘K’ values + for internal and leaf nodes of a group or indexed storage v1 + B-trees. This message is <em>only</em> found in the superblock + extension.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: B-tree ‘K’ Values Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="2">Indexed Storage Internal Node K</td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Group Internal Node K</td> + <td colspan="2">Group Leaf Node K</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: B-tree ‘K’ Values Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each internal node of an + indexed storage v1 B-tree. See the description of this field + in version 0 and 1 of the superblock as well the section on + v1 B-trees. + </p> + </td> + </tr> + + <tr> + <td><p>Group Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each internal node of a group + v1 B-tree. See the description of this field in version 0 and + 1 of the superblock as well as the section on v1 B-trees. + </p> + </td> + </tr> + + <tr> + <td><p>Group Leaf Node K</p></td> + <td><p>This is the node ‘K’ value for each leaf node of a group v1 + B-tree. See the description of this field in version 0 and 1 + of the superblock as well as the section on v1 B-trees. + </p> + </td> + </tr> + + </table> +</div> + +<h4><a name="DrvInfoMessage">IV.A.2.u. The Driver Info + Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Driver + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0014</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + + <tr><td> + <b>Description:</b></td> + <td>This message contains information needed by the file driver + to reopen a file. This message is <em>only</em> found in the + superblock extension: see the <a href="#SuperblockExt"> + “Disk Format: Level 0C - Superblock Extension”</a> + section for more information. For more information on the fields + in the driver info message, see the <a href="#DriverInfo"> + “Disk Format: Level 0B - File Driver Info”</a> + section; those who use the multi and family file drivers will + find this section particularly helpful.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Driver Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Driver Identification</td> + </tr> + + <tr> + <td colspan="2">Driver Information Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Driver Information <em>(variable size)</em><br /><br /><br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Driver Info Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td><p>This is an eight-byte ASCII string without null termination which + identifies the driver. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td><p>The size in bytes of the <em>Driver Information</em> field of this + message.</p> + </td> + </tr> + + <tr> + <td><p>Driver Information</p></td> + <td><p>Driver information is stored in a format defined by the file driver.</p> + </td> + </tr> + </table> +</div> + +<h4><a name="AinfoMessage">IV.A.2.v. The Attribute Info + Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Attribute + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0015</td></tr> + <tr><td colspan="2"><b>Length:</b> Varies</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message stores information about the attributes on an + object, such as the maximum creation index for the attributes + created and the location of the attribute storage when the + attributes are stored “densely”.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Attribute Info Message + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Maximum Creation Index <em>(optional)</em></td> + </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Name v2 B-tree Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Creation Order v2 B-tree Address<sup>O</sup> <em>(optional)</em><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Attribute Info Message + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the attribute index information flag with the + following definition: + + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, creation order for attributes is tracked. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, creation order for attributes is indexed. + </td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>The is the maximum creation order index value for the + attributes on the object.</p> + <p>This field is present if bit 0 of <em>Flags</em> is set.</p> + </td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td><p>This is the address of the fractal heap to store dense + attributes. + Each attribute stored in the fractal heap is described by + the <a href="#AttributeMessage">Attribute Message.</a> + </p> + </td> + </tr> + + <tr> + <td><p>Attribute Name v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index the + names of densely stored attributes.</p> + </td> + </tr> + + <tr> + <td><p>Attribute Creation Order v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index the + creation order of densely stored attributes.</p> + <p>This field is present if bit 1 of <em>Flags</em> is set.</p> + </td> + </tr> + + </table> +</div> + +<h4><a name="RefCountMessage">IV.A.2.w. The Object Reference + Count Message</a></h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> Object Reference + Count</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0016</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td><b>Description:</b></td> + <td>This message stores the number of hard links (in groups or + objects) pointing to an object: in other words, its + <em>reference count</em>.</td></tr> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption> + Layout: Object Reference Count + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Reference count</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Object Reference Count + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td><p>The unsigned 32-bit integer is the reference count for the + object. This message is only present in “version 2” + (or later) object headers, and if not present those object + header versions, the reference count for the object is assumed + to be 1.</p> + </td> + </tr> + + </table> +</div> + +<br /> + +<h4><a name="FsinfoMessage">IV.A.2.x. The File Space Info + Message</a></h4> + +<center> + <table class="msgdesc"> + <tr><td colspan="2"><b>Header Message Name:</b> File Space + Info</td></tr> + <tr><td colspan="2"><b>Header Message Type:</b> 0x0017</td></tr> + <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> + <tr><td colspan="2"><b>Status:</b> Optional; may not be + repeated.</td></tr> + <tr><td> + <b>Description:</b></td> + <td>This message stores the file space management information + that the library uses in handling file space + requests for the file. Version 0 of the message is used for release 1.10.0 only. + Version 1 of the message is used for release 1.10.1+. + There is no File Space Info message before release 1.10 as the library does + not track file space across multiple file opens. + <p> + Note that version 0 is deprecated starting release 1.10.1. + That means when the 1.10.1+ library opens an HDF5 file with a version 0 message, + the library will decode and map the message to version 1. + On file close, it will encode the message as a version 1 message. + <p> + The library uses the following three mechanisms to manage file space in an HDF5 file: + <ul> + <li> Free-space managers + <br> They track free-space sections of various sizes in the file that are not currently + allocated. Each free-space manager corresponds to a file space type. + There are two main groups of file space types: metadata and raw data. + Metadata is further divided into five types: superblock, B-tree, global heap, + local heap, and object header. + See the description of <a href="#FreeSpaceManager">Free-space + Manager</a> as well the description of file space allocation types in + <a href="#AppendixB">Appendix B</a> + </li> + <li> Aggregators + <br> The library manages two aggregators, one for metadata and one for raw data. + Aggregator is a contiguous block of free-space in the file. + The size of each aggregator is tunable via public routines + <code>H5Pset_meta_block_size</code> and <code>H5Pset_small_data_block_size</code> respectively. + </li> + <li> Virtual file drivers + <br> The library's virtual file driver interface dispatches requests for additional + space to the allocation routine of the file driver associated with the file. + For example, if the sec2 file driver is being used, its allocation routine will + increase the size of the file to service the requests. + </li> + </ul> + <p> + For release 1.10.0, the library derives the following four file space strategies + based on the mechanisms: + <ul> + <li>H5F_FILE_SPACE_ALL + <ul> + <li>Mechanisms used: free-space managers, aggregators, and virtual file drivers</li> + <li>Does not persist free-space across file opens</li> + <li>This strategy is the library default</li> + </ul> + </li> + <li>H5F_FILE_SPACE_ALL_PERSIST</li> + <ul> + <li>Mechanisms used: free-space managers, aggregators, and virtual file drivers</li> + <li>Persist free-space across file opens</li> + </ul> + <li>H5F_FILE_SPACE_AGGR_VFD</li> + <ul> + <li>Mechanisms used: aggregators and virtual file drivers</li> + <li>Does not persist free-space across file opens</li> + </ul> + <li>H5F_FILE_SPACE_VFD</li> + <ul> + <li>Mechanisms used: virtual file drivers</li> + <li>Does not persist free-space across file opens</li> + </ul> + </ul> + For release 1.10.1+, the free-space manager mechanism is modified to handle paged aggregation + which aggregates small metadata and raw data allocations into constant-sized well-aligned pages + to allow efficient I/O accesses. + With the support of this feature, the library derives the following four file space strategies: + <ul> + <li>H5F_FSPACE_STRATEGY_FSM_AGGR </li> + <ul> + <li>Mechanisms used: free-space managers, aggregators, and virtual file drivers</li> + <li>This strategy is the library default</li> + </ul> + <li>H5F_FSPACE_STRATEGY_PAGE</li> + <ul> + <li>Mechanisms used: free-space managers with embedded paged aggregation and virtual file drivers</li> + </ul> + <li>H5F_FSPACE_STRATEGY_AGGR</li> + <ul> + <li>Mechanisms used: aggregators and virtual file drivers</li> + </ul> + <li>H5F_FSPACE_STRATEGY_NONE</li> + <ul> + <li>Mechanisms used: virtual file drivers</li> + </ul> + </ul> + The default is not persisting free-space across file opens for the above four strategies. + User can use the public routine <code>H5Pset_file_space_strategy</code> to request + persisting free-space. + </td></tr> + <p> + <tr><td colspan="2"><b>Format of Data:</b> See the tables + below.</td></tr> +</table></center> +<p> + <div align="center"> + <table class="format"> + <caption> + Layout: File Space Info - Version 0 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Strategy</td> + <td colspan="2">Threshold<sup>L</sup></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>O</sup> for H5FD_MEM_SUPER<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>0</sup> for H5FD_MEM_BTREE<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>0</sup> for H5FD_MEM_DRAW<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>0</sup> for H5FD_MEM_GHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>0</sup> for H5FD_MEM_LHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Free-space manager address<sup>0</sup> for H5FD_MEM_OHDR<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: File Space Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>This is version 0 of this message.</p> + </td> + </tr> + + <tr> + <td><p>Strategy</p></td> + <td><p>This is the file space strategy used to manage file space. + There are four types: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>H5F_FILE_SPACE_ALL_PERSIST</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>H5F_FILE_SPACE_ALL</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>H5F_FILE_SPACE_AGGR_VFD</td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>H5F_FILE_SPACE_VFD</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Threshold</p></td> + <td><p>This is the smallest free-space section size that the + free-space manager will track. + </td> + </tr> + <tr> + <td><p>Free-space manager addresses</p></td> + <td><p>These are the six free-space manager addresses for the + six file space allocation types: + <ul> + <li>H5FD_MEM_SUPER</li> + <li>H5FD_MEM_BTREE</li> + <li>H5FD_MEM_DRAW</li> + <li>H5FD_MEM_GHEAP</li> + <li>H5FD_MEM_LHEAP</li> + <li>H5FD_MEM_OHDR</li> + </ul> + Note that these six fields exist only if the value for the field + “<em>Strategy</em>” is H5F_FILE_SPACE_ALL_PERSIST. + </p> + </td> + </tr> + + </table> + </div> + <br /> + + <div align="center"> + <table class="format"> + <caption> + Layout: File Space Info - Version 1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Strategy</td> + <td>Persisting free-space</td> + <td colspan="1" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Free-space Section Threshold<sup>L</sup></td> + </tr> + + <tr> + <td colspan="4">File Space Page Size</td> + </tr> + + <tr> + <td colspan="2">Page-end Metadata threshold</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />EOA<sup>0</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FD_MEM_SUPER<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FD_MEM_BTREE<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FM_MEM_DRAW<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FD_MEM_GHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FD_MEM_LHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of small-sized free-space manager for H5FD_MEM_OHDR<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FD_MEM_SUPER<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FD_MEM_BTREE<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FM_MEM_DRAW<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FD_MEM_GHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FD_MEM_LHEAP<br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Address<sup>O</sup> of large-sized free-space manager for H5FD_MEM_OHDR<br /><br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: File Space Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>This is version 1 of this message.</p> + </td> + </tr> + + <tr> + <td><p>Strategy</p></td> + <td><p>This is the file space strategy used to manage file space. + There are four types: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>H5F_FSPACE_STRATEGY_FSM_AGGR</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>H5F_FSPACE_STRATEGY_PAGE</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>H5F_FSPACE_STRATEGY_AGGR</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>H5F_FSPACE_STRATEGY_NONE</td> + </tr> + </table></p> + </td> + </tr> + + <tr> + <td><p>Persisting free-space</p></td> + <td><p>True or false in persisting free-space. + </td> + </tr> + + <tr> + <td><p>Free-space Section Threshold</p></td> + <td><p>This is the smallest free-space section size that the + free-space manager will track. + </td> + </tr> + + <tr> + <td><p>File space page size</p></td> + <td><p>This is the file space page size, which is used when the paged aggregation feature + is enabled. + </td> + </tr> + + <tr> + <td><p>Page-end metadata threshold</p></td> + <td><p>This is the smallest free-space section size at the end of a page that + the free-space manager will track. This is used when the paged aggregation feature + is enabled. + </td> + </tr> + + <tr> + <td><p>EOA</p></td> + <td><p>The EOA before the allocation of free-space manager header and section info for the + self-referential free-space managers when persisting free-space. + <br> + Note that self-referential free-space managers are managers that involve file space + allocation for the managers' free-space header and section info. + </td> + </tr> + + <tr> + <td><p>Addresses of small-sized free-space managers</p></td> + <td><p>These are the addresses of the six small-sized free-space managers for + the six file space allocation types: + </p> + <ul> + <li>H5FD_MEM_SUPER</li> + <li>H5FD_MEM_BTREE</li> + <li>H5FD_MEM_DRAW</li> + <li>H5FD_MEM_GHEAP</li> + <li>H5FD_MEM_LHEAP</li> + <li>H5FD_MEM_OHDR</li> + </ul> + Note that these six fields exist only if the value for the field + “<em>Persisting free-space</em>” is true. +</ul> +</td> +</tr> + +<tr> + <td><p>Addresses of large-sized free-space managers</p></td> + <td><p>These are the addresses of the six large-sized free-space managers for + the six file space allocation types: + </p> + <ul> + <li>H5FD_MEM_SUPER</li> + <li>H5FD_MEM_BTREE</li> + <li>H5FD_MEM_DRAW</li> + <li>H5FD_MEM_GHEAP</li> + <li>H5FD_MEM_LHEAP</li> + <li>H5FD_MEM_OHDR</li> + </ul> + Note that these six fields exist only if the value for the field + “<em>Persisting free-space</em>” is true. +</ul> +</td> +</tr> + +</table> +</div> + +<h3><a name="DataStorage"> + IV.B. Disk Format: Level 2B - Data Object Data Storage</a></h3> + +<p>The data for an object is stored separately from its header + information in the file and may not actually be located in the HDF5 file + itself if the header indicates that the data is stored externally. The + information for each record in the object is stored according to the + dimensionality of the object (indicated in the dataspace header message). + Multi-dimensional array data is stored in C order; in other words, the + “last” dimension changes fastest.</p> + +<p>Data whose elements are composed of atomic datatypes are stored in IEEE + format, unless they are specifically defined as being stored in a different + machine format with the architecture-type information from the datatype + header message. This means that each architecture will need to [potentially] + byte-swap data values into the internal representation for that particular + machine.</p> + +<p> Data with a variable-length datatype is stored in the global heap + of the HDF5 file. Global heap identifiers are stored in the + data object storage.</p> + +<p>Data whose elements are composed of reference datatypes are stored in + several different ways depending on the particular reference type involved. + Object pointers are just stored as the offset of the object header being + pointed to with the size of the pointer being the same number of bytes as + offsets in the file.</p> + +<p>Dataset region references are stored as a heap-ID which points to + the following information within the file-heap: an offset of the object + pointed to, number-type information (same format as header message), + dimensionality information (same format as header message), sub-set start + and end information (in other words, a coordinate location for each), + and field start and end names (in other words, a [pointer to the] string + indicating the first field included and a [pointer to the] string name + for the last field). </p> + +<p>Data of a compound datatype is stored as a contiguous stream of the items + in the structure, with each item formatted according to its datatype. +<p> + Description of datatypes for variable-length, references and compound classes can be found + in <a href="#DatatypeMessage">Datatype Message</a>. +<p> + Information about global heap and heap ID can be found in <a href="#GlobalHeap">Global Heap</a>. +<p> + For reference datatype, + see also the encoding description for <a href="#ReferenceEncodeRV">Reference Encoding (Revised) </a> and + <a href="#ReferenceEncodeDP">Reference Encoding (Backward Compatibility)</a> in Appendix D. +</p> + +<h2><a name="AppendixA"> + V. Appendix A: Definitions</a></h2> + +<p>Definitions of various terms used in this document are included in + this section.</p> + +<div align="center"> + <table class="glossary"> + <tr> + <th width="20%">Term</th> + <th>Definition</th> + </tr> + + <tr> + <td>Undefined Address</td> + <td>The <a name="UndefinedAddress">undefined + address</a> for a file is a file address with all bits + set: in other words, <code>0xffff...ff</code>.</td> + </tr> + + <tr> + <td>Unlimited Size</td> + <td>The <a name="UnlimitedDim">unlimited size</a> + for a size is a value with all bits set: in other words, + <code>0xffff...ff</code>.</td> + </tr> + + </table> +</div> + + +<h2><a name="AppendixB"> + VI. Appendix B: File Space Allocation Types</a></h2> + +<p>There are six basic types of file space allocation as follows: +</p> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Description</th> + </tr> + + <tr> + <td>H5FD_MEM_SUPER</td> + <td>File space allocated for <em>Superblock.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_BTREE</td> + <td>File space allocated for <em>B-tree.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_DRAW</td> + <td>File space allocated for <em>raw data</em>.</td> + </tr> + + <tr> + <td>H5FD_MEM_GHEAP</td> + <td>File space allocated for <em>Global Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>File space allocated for <em>Local Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>File space allocated for <em>Object Header.</em></td> + </tr> + </table> +</div> + +<br /> +<p>There are other file space allocation types that are mapped to the + above six basic types because they are similar in nature. + The mapping and the corresponding description are listed in the following two tables: +</p> + +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Mapping of Allocation Types to Basic Allocation Types</th> + </tr> + + <tr> + <td>H5FD_MEM_SUPER</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_BTREE</td> + <td>H5FD_MEM_SOHM_INDEX</td> + </tr> + + <tr> + <td>H5FD_MEM_DRAW</td> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + </tr> + + <tr> + <td>H5FD_MEM_GHEAP</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>H5FD_MEM_FHEAP_DBLOCK, H5FD_MEM_FSPACE_SINFO</td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>H5FD_MEM_FHEAP_HDR, H5FD_MEM_FHEAP_IBLOCK, H5FD_MEM_FSPACE_HDR, H5FD_MEM_SOHM_TABLE</td> + </tr> + </table> +</div> + +<br /> +</p> + +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Allocation Type</th> + <th>Description</th> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HDR</td> + <td>File space allocated for <em>Fractal Heap Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_DBLOCK</td> + <td>File space allocated for <em>Fractal Heap Direct Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_IBLOCK</td> + <td>File space allocated for <em>Fractal Heap Indirect Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + <td>File space allocated for huge objects in the fractal heap.</td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_HDR</td> + <td>File space allocated for <em>Free-space Manager Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_SINFO</td> + <td>File space allocated for <em>Free-space Section List</em> of the free-space manager.</td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_TABLE</td> + <td>File space allocated for <em>Shared Object Header Message Table.</em></td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_INDEX</td> + <td>File space allocated for <em>Shared Message Record List.</em></td> + </tr> + </table> +</div> + +<h2><a name="AppendixC"> VII. Appendix C: + Types of Indexes for Dataset Chunks</a></h2> + +<p>For an HDF5 file without the latest format enabled, the library + uses the <a href="#V1Btrees">Version 1 B-tree</a> to index dataset + chunks.</p> + +<p>For an HDF5 file with the latest format enabled, the library uses + one of the following five indexing types depending on a chunked + dataset’s dimension specification and the way it is extended. +</p> + +<a name="SingleChunk"> + <h3>VII.A. The Single Chunk Index</h3></a> + +<p>The <i>Single Chunk</i> index can be used when the dataset fulfills + the following condition:</p> + +<ul> + <li>the current, maximum, and chunk dimension sizes are all the same</li> +</ul> + +<p>The dataset has only one chunk, and the address of the single + chunk is stored in the version 4 <i>Data Layout</i> message. + See the <a href="#ChunkedStorage">Chunked Storage Property + Description</i></a> layout and field description tables.</p> + +<a name="Implicit"> + <h3>VII.B. The Implicit Index</h3></a> + +<p>The <i>Implicit</i> index can be used when the dataset fulfills + the following conditions:</p> + +<ul> + <li>fixed maximum dimension sizes</li> + <li>no filter applied to the dataset</li> + <li>the timing for the space allocation of the dataset chunks is + <code>H5P_ALLOC_TIME_EARLY</code></li> +</ul> + +<p>Since the dataset’s dimension sizes are known and storage space + is to be allocated early, an array of dataset chunks are allocated + based on the maximum dimension sizes when the dataset is created. + The base address of the array is stored in the version 4 + <i>Data Layout</i> message. See the + <a href="#ChunkedStorage">Chunked Storage Property + Description</i></a> layout and field description tables. +</p> + +<p>When accessing a dataset chunk with a specified offset, the + address of the chunk in the array is computed as below:</p> + +<dir><p><code>base address + (size of a chunk in bytes * chunk index + associated with the offset)</code></p></dir> + +<p>A chunk index starts at 0 and increases according to the + fastest changing dimension, then the next fastest, and so on. + <a name="ChunkIndex"></a> + The chunk index for a dataset chunk offset is computed as below: + <ol> + <li>Calculate the scaled offset for each dimension in + <code>scaled_offset</code>: + <br /> + <pre> + scaled_offset = chunk_offset/chunk_dims + </pre></li> + <li>Calculate the # of chunks for each dimension in + <code>nchunks</code>: + <br /> + <pre> + nchunks = (curr_dims + chunk_dims - 1)/chunk_dims + </pre></li> + + <li>Calculate the down chunks for each dimension in + <code>down_chunks</code>: + <br /> + <pre> + /* n is the # of dimensions */ + for(i = (int)(n-1), acc = 1; i >= 0; i--) { + down_chunks[i] = acc; + acc *= nchunks[i]; + } + </pre> + </li> + + <li>Calculate the chunk index in <code>chunk_index</code>: + <br /> + <pre> + /* n is the # of dimensions */ + for(u = 0, chunk_index = 0; u < n; u++) + chunk_index += down_chunks[u] * scaled_offset[u]; + </pre> + </li> + </ol> +<p> + For example, for a 2-dimensional dataset with + <code>curr_dims[4,5]</code> and <code>chunk_dims[3,2]</code>, + there will be a total of 6 chunks, with 3 chunks in the fastest + changing dimension and 2 chunks in the slowest changing dimension. + See the figure below. + The chunk index for the chunk offset <code>[3,4]</code> + is computed as below: + <ol> + <code> + <li>scaled_offset[0] = 1, scaled_offset[1] = 2</li> + <li>nchunks[0] = 2, nchunks[1] = 3</li> + <li>down_chunks[0] = 3, down_chunks[1] = 1</li> + <li>chunk_index = 5</li> + </code> + </ol> + + + <table align="center" width="400" border="0"> + <tr valign="center" align="center"> + <td> + <hr size="2"/> + <img height="250" src="FileFormatSpecChunkDiagram.jpg" + alt="Chunk Diagram"></td> + </tr> + <tr valign="top" align="center"> + <td> + <hr size="1" /> + <b>Figure 3. Implicit index chunk diagram </b> + <hr size="2"/></td> + </tr> + </table> + + + + + + <a name="FixedArray"> + <h3>VII.C. The Fixed Array Index</h3></a> + +<p>The <i>Fixed Array</i> index can be used when the dataset fulfills + the following condition:</p> +<ul> + <li>fixed maximum dimension sizes</li> +</ul> + +<p>Since the maximum number of chunks is known, an array of + in-file-on-disk addresses based on the maximum number of chunks is + allocated when data is written to the dataset. To access a dataset + chunk with a specified offset, the + <a href="#ChunkIndex">chunk index</i></a> associated with the offset +is calculated. The index is mapped into the array to locate the +disk address for the chunk.</p> + +<p>The Fixed Array (FA) index structure provides space and speed + improvements in locating chunks over index structures that handle + more dynamic data accesses like a + <a href="#AppendV2Btrees">Version 2 B-tree</a> index. + The entry into the Fixed Array is the Fixed Array header which + contains metadata about the entries stored in the array. The + header contains a pointer to a data block which stores the array + of entries that describe the dataset chunks. For greater efficiency, + the array will be divided into multiple pages if the number of + entries exceeds a threshold value. The space for the data block + and possibly data block pages are allocated as a single contiguous + block of space.</p> + +<p>The content of the data block depends on whether paging is + activated or not. When paging is not used, elements that describe + the chunks are stored in the data block. If paging is turned on, + the data block contains a bitmap indicating which pages are + initialized. Then subsequent data block pages will contain the + entries that describe the chunks.</p> + +<p>An entry describes either a filtered or non-filtered dataset + chunk. The formats for both element types are described below. +</p> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fixed Array Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td>Entry Size</td> + <td>Page Bits</td> + </tr> + + <tr> + <td colspan="4"><br />Max Num + Entries<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Block + Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fixed Array Header + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FAHD</code>” + is used to indicate the beginning of a Fixed Array header. + This gives file consistency checking utilities a better + chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The ID for identifying the client of the + Fixed Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Entry Size</p></td> + <td> + <p>The size in bytes of an entry in the Fixed Array. + </p> + </td> + </tr> + + <tr> + <td><p>Page Bits</p></td> + <td> + <p>The number of bits needed to store the maximum + number of entries in a + <a href="#FADataBlockPage">data block page.</a></p> + </td> + </tr> + + <tr> + <td><p>Max Num Entries</p></td> + <td> + <p>The maximum number of entries in the Fixed + Array.</p> + </td> + </tr> + + <tr> + <td><p>Data Block Address</p></td> + <td> + <p>The address of the data block in the Fixed Array. + </p> + </td> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the header.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Fixed Array Data Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Page Bitmap <em>(variable size and + optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Elements <em>(variable size and + optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fixed Array Data Block + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>FADB</code>” + is used to indicate the beginning of a Fixed Array data + block. This gives file consistency checking utilities a + better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The ID for identifying the client of the + Fixed Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Header Address</p></td> + <td> + <p>The address of the Fixed Array header. Principally used + for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Page Bitmap</p></td> + <td><p>A bitmap indicating which data block pages are initialized.</p> + <p>Exists only if the data block is paged.</p></td> + </tr> + + <tr> + <td><p>Elements</p></td> + <td> + <p>Contains the elements stored in the data block + and exists only if the data block is not paged. + There are two element types: + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#FaNonFilterChunk">Non-filtered + dataset chunks</i></a> +</td> +</tr> +<tr> + <td align="center"><code>1</code></td> + <td><a href="#FaFilterChunk">Filtered dataset + chunks</i></a> +</td> +</tr> +</table> +</p> +</td> +</tr> + +<tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the Fixed Array data block.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption><a name="FADataBlockPage"> + Layout: Fixed Array Data Block Page</a> + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Elements <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Fixed Array Data Block Page + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Elements</p></td> + <td> + <p>Contains the elements stored in the data block page. + There are two element types: + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#FaNonFilterChunk">Non-filtered dataset chunks</i></a> +</td> +</tr> +<tr> + <td align="center"><code>1</code></td> + <td><a href="#FaFilterChunk">Filtered dataset chunks</i></a> +</td> +</tr> +</table> +</p> +</td> +</tr> + +<tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for a Fixed Array data block page.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<a name="FaNonFilterChunk"></a> +<div align="center"> + <table class="format"> + <caption> + Layout: Data Block Element for Non-filtered Dataset Chunk + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Data Block Element for Non-filtered Dataset Chunk + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the dataset chunk in the file. + </p> + </td> + </tr> + + </table> +</div> +<!-- </p> --> + +<br /> +<br /> +<br /> +<a name="FaFilterChunk"></a> +<div align="center"> + <table class="format"> + <caption> + Layout: Data Block Element for Filtered Dataset Chunk + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Chunk Size <em>(variable size; at most + 8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filter Mask</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Data Block Element for Filtered Dataset Chunk + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the dataset chunk in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Chunk Size</p></td> + <td><p>The size of the dataset chunk in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td><p>Indicates the filter to skip for the dataset chunk. Each + filter has an index number in the pipeline; if that filter is + skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + </table> +</div> + +<a name="ExtensibleArray"> + <h3>VII.D. The Extensible Array Index</h3></a> + +<p>The <i>Extensible Array</i> index can be used when the dataset + fulfills the following condition:</p> + +<ul> + <li>only one dimension of unlimited extent</li> +</ul> + +<p>The Extensible Array (EA) is a data structure that is used as a + chunk index in datasets where the dataspace has a single + unlimited dimension. In other words, one dimension is set to + <code>H5S_UNLIMITED</code>, and the other dimensions are any number + of fixed-size dimensions. The idea behind the extensible array is + that a particular data object can be located via a lightweight + indexing structure of fixed depth for a given address space. This + indexing structure requires only a few (2-3) file operations per + element lookup and gives good cache performance. Unlike the B-tree + structure, the extensible array is optimized for appends. Where a + B-tree would always add at the rightmost node under these + circumstances, either creating a deep tree (version 1) or requiring + expensive rebalances to correct (version 2), the extensible array + has already mapped out a pre-balanced internal structure. This + optimized internal structure is instantiated as needed when chunk + records are inserted into the structure.</p> + + + +<!-- + + <p>A description of the rationale that leads to the present + implementation of the extensible array can be found at + <a href="https://svn.hdfgroup.org/hdf5doc/trunk/projects/1_10_alpha/ReviseChunks/skip_lists"> + https://svn.hdfgroup.org/hdf5doc/trunk/projects/1_10_alpha/ReviseChunks/skip_lists</a>. + </p> + +<p>The current implementation differs from the data structure + described in that reference in some ways, but the basic idea is the + same.</p> + +--> + + + +<p>An Extensible Array consists of a header, an index block, + secondary blocks, data blocks, and (optional) data block pages. The + general scheme is that the index block is used to reference a + secondary block, which is, in turn, used to reference the data block + page where the chunk information is stored. The data blocks will + be paged for efficiency when their size passes a threshold value. + These pages are laid out contiguously on the disk after the data + block, are initialized as needed, and are tracked via bitmaps + stored in the secondary block. The number of secondary and data + blocks/pages in a chunk index varies as they are allocated as + needed and the first few are (conceptually) stored in parent + elements as an optimization.</p> + +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Header + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td>Element Size</td> + <td>Max Nelmts Bits</td> + </tr> + + <tr> + <td>Index Blk Elmts</td> + <td>Data Blk Min Elmts</td> + <td>Secondary Blk Min Data Ptrs</td> + <td>Max Data Blk Page Nelmts Bits</td> + </tr> + + <tr> + <td colspan="4"><br />Num Secondary Blks<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Secondary Blk Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Num Data Blks<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Data Blk Size<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Max Index Set<sup>L</sup><br /><br /></td> + </tr> + <tr> + <td colspan="4"><br />Num Elements<sup>L</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Index Block Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘L’ in the above table are + of the size specified in the <a href="#SizeOfLengthsV0">Size + of Lengths</a> field in the superblock.) + </td></tr> + <tr> + <td> </td> + <td> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Header + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>EAHD</code>” + is used to indicate the beginning of an Extensible Array + header. This gives file consistency checking utilities a + better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The ID for identifying the client of the + Fixed Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Element Size</p></td> + <td> + <p>The size in bytes of an element in the Extensible Array. + </p> + </td> + </tr> + + <tr> + <td><p>Max Nelmts Bits</p></td> + <td> + <p>The number of bits needed to store the + maximum number of elements in the Extensible Array.</p> + </td> + </tr> + + <tr> + <td><p>Index Blk Elmts</p></td> + <td> + <p>The number of elements to store in the index block. + </p> + </td> + </tr> + + <tr> + <td><p>Data Blk Min Elmts</p></td> + <td> + <p>The minimum number of elements per data block. + </p> + </td> + </tr> + + <tr> + <td><p>Secondary Blk Min Data Ptrs</p></td> + <td> + <p>The minimum number of data block pointers for a + secondary block. + </p> + </td> + </tr> + + <tr> + <td><p>Max Dblk Page Nelmts Bits</p></td> + <td> + <p>The number of bits needed to store the maximum number + of elements in a data block page. + </p> + </td> + </tr> + + <tr> + <td><p>Num Secondary Blks</p></td> + <td> + <p>The number of secondary blocks created. + </p> + </td> + </tr> + + <tr> + <td><p>Secondary Blk Size</p></td> + <td> + <p>The size of the secondary blocks created. + </p> + </td> + </tr> + + <tr> + <td><p>Num Data Blks</p></td> + <td> + <p>The number of data blocks created. + </p> + </td> + </tr> + + <tr> + <td><p>Data Blk Size</p></td> + <td> + <p>The size of the data blocks created. + </p> + </td> + </tr> + + <tr> + <td><p>Max Index Set</p></td> + <td> + <p>The maximum index set. + </p> + </td> + </tr> + + <tr> + <td><p>Num Elmts</p></td> + <td> + <p>The number of elements realized. + </p> + </td> + </tr> + + <tr> + <td><p>Index Block Address</p></td> + <td> + <p>The address of the index block. + </p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the header.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Index Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Elements <em>(variable size and + optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Block Addresses <em>(variable + size and optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Secondary Block Addresses <em>(variable + size and optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Index Block + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>EAIB</code>” + is used to indicate the beginning of an Extensible Array + Index Block. This gives file consistency checking utilities + a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The client ID for identifying the user of the + Extensible Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Header Address</p></td> + <td> + <p>The address of the Extensible Array header. Principally + used for file integrity checking.</p> + </td> + </tr> + + <tr> + <td><p>Elements</p></td> + <td> + <p>Contains the elements that are stored directly in + the index block. An optimization to avoid unnecessary + secondary blocks. + <br /> + <br /> + There are two element types: + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#EaNonFilterChunk">Non-filtered dataset chunks</i></a> +</td> +</tr> +<tr> + <td align="center"><code>1</code></td> + <td><a href="#EaFilterChunk">Filtered dataset chunks</i></a> +</td> +</tr> +</table> +</p> +</td> +</tr> + +<tr> + <td><p>Data Block Addresses</p></td> + <td> + <p>Contains the addresses of the data blocks + that are stored directly in the Index Block. An + optimization to avoid unnecessary secondary blocks.</p> + </td> +</tr> + +<tr> + <td><p>Secondary Block Addresses</p></td> + <td> + <p>Contains the addresses of the secondary + blocks.</p> + </td> +</tr> + +<tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the Extensible Array Index Block.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Secondary Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Block Offset <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Page Bitmap <em>(variable size and + optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Block Addresses <em>(variable + size and optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Secondary Block + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>EASB</code>” + is used to indicate the beginning of an Extensible Array + Secondary Block. This gives file consistency checking utilities + a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The ID for identifying the client of the + Extensible Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Header Address</p></td> + <td> + <p>The address of the Extensible Array header. Principally + used for file integrity checking.</p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>Stores the offset of the block in the array. + </p> + </td> + </tr> + + <tr> + <td><p>Page Bitmap</p></td> + <td> + <p>A bitmap indicating which + data block pages are initialized. + <p> + Exists only if the data block is paged. + </td> + </tr> + + <tr> + <td><p>Data Block Addresses</p></td> + <td> + <p>Contains the addresses of the data blocks + referenced by this secondary block.</p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the Extensible Array + Secondary Block.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Data Block + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + + <tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Block Offset <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Elements <em>(variable size and + optional)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Data Block + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p>The ASCII character string “<code>EADB</code>” + is used to indicate the beginning of an Extensible Array + data block. This gives file consistency checking utilities + a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Client ID</p></td> + <td> + <p>The ID for identifying the client of the + Extensible Array: + + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Non-filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Filtered dataset chunks + </td> + </tr> + <tr> + <td align="center"><code>2+</code></td> + <td>Reserved. + </td> + </tr> + </table> + </p> + </td> + </tr> + + <tr> + <td><p>Header Address</p></td> + <td> + <p>The address of the Extensible Array header. Principally + used for file integrity checking. + </p> + </td> + </tr> + + <tr> + <td><p>Block Offset</p></td> + <td> + <p>The offset of the block in the array. + </td> + </tr> + + <tr> + <td><p>Elements</p></td> + <td> + <p>Contains the elements stored in the data block and + exists only if the data block is not paged. + <br /> + <br /> + There are two element types: + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#EaNonFilterChunk">Non-filtered dataset chunks</i></a> +</td> +</tr> +<tr> + <td align="center"><code>1</code></td> + <td><a href="#EaFilterChunk">Filtered dataset chunks</i></a> +</td> +</tr> +</table> +</p> +</td> +</tr> + +<tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for the Extensible Array data block.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption> + Layout: Extensible Array Data Block Page + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4"><br />Elements <em>(variable + size)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Extensible Array Data Block Page + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Elements</p></td> + <td> + <p>Contains the elements stored in the data block + page.</p> + <p> + There are two element types: + <table class="list"> + <tr> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td><a href="#EaNonFilterChunk">Non-filtered dataset chunks</i></a> +</td> +</tr> +<tr> + <td align="center"><code>1</code></td> + <td><a href="#EaFilterChunk">Filtered dataset chunks</i></a> +</td> +</tr> +</table> +</p> +</td> +</tr> + +<tr> + <td><p>Checksum</p></td> + <td> + <p>The checksum for an Extensible Array data block + page.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> +<a name="EaNonFilterChunk"></a> +<div align="center"> + <table class="format"> + <caption> + Layout: Data Block Element for Non-filtered Dataset Chunk + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr><td> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Data Block Element for Non-filtered Dataset Chunk + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the dataset chunk in the file. + </p> + </td> + </tr> + + </table> +</div> +</p> + +<br /> +<br /> +<br /> +<a name="EaFilterChunk"></a> +<div align="center"> + <table class="format"> + <caption> + Layout: Data Block Element for Filtered Dataset Chunk + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br />Chunk Size<em> (variable size; at + most 8 bytes)</em><br /><br /></td> + </tr> + + <tr> + <td colspan="4">Filter Mask</td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Data Block Element for Filtered Dataset Chunk + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the dataset chunk in the file. + </p> + </td> + </tr> + + <tr> + <td><p>Chunk Size</p></td> + <td><p>The size of the dataset chunk in bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Filter Mask</p></td> + <td><p>Indicates the filter to skip for the dataset chunk. + Each filter has an index number in the pipeline; if that + filter is skipped, the bit corresponding to its index is set. + </p> + </td> + </tr> + + </table> +</div> + +<a name="AppendV2Btrees"> + <h3>VII.E. The Version 2 B-trees Index</h3></a> + +<p>The <i>Version 2 B-trees</i> index can be used when the dataset + fulfills the following condition:</p> + +<ul> + <li>more than one dimension of unlimited extent</li> +</ul> + +<p>Version 2 B-trees can be used to index various objects in the + library. See <a href="#V2Btrees">“Version 2 B-trees”</a> + for more information. The B-tree types <a href="#V2BtType10">10</a> + and <a href="#V2BtreesType11">11</a> record layouts are for + indexing dataset chunks.</p> + +<h2><a name="AppendixD"> VIII. Appendix D: + Encoding for dataspace and reference</a></h2> + +<a name="DataspaceEncode"> + <h3>VIII.A. Dataspace Encoding </h3></a> +<i>H5Sencode</i> is a public routine that encodes a dataspace description into a buffer while +<i>H5Sdecode</i> is the corresponding routine that decodes the description encoded in the buffer. +<p> + See the reference manual description for these two public routines. + + <br /> + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Dataspace Description for H5Sencode/H5Sdecode + </caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Dataspace ID</td> + <td>Encode Version</td> + <td>Size of Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Size of Extent + <br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Dataspace Message + <em>(variable size)</em> + <br /><br /></td> + </tr> + + <tr> + <td colspan="4"><br /><br />Dataspace Selection + <em>(variable size)</em> + <br /><br /></td> + </tr> + + </table> + + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Dataspace Description for H5Sencode/H5Sdecode + </caption> + <tr> + <th width="40%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dataspace ID</p></td> + <td> + <p>The datspace message ID which is 1.</p> + </td> + </tr> + + <tr> + <td><p>Encode Version</p></td> + <td> + <p>H5S_ENCODE_VERSION which is 0. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Size</p></td> + <td> + <p>The number of bytes used to store the size of an object. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Extent</p></td> + <td> + <p>Size of the dataspace message. + </p> + </td> + </tr> + + <tr> + <td><p>Dataspace Message</p></td> + <td> + <p>The dataspace message information. See + <a href="#DataspaceMessage">Dataspace Message.</a></p> +</p> +</td> +</tr> + +<tr> + <td><p>Dataspace Selection</p></td> + <td> + <p>The dataspace selection information. See + <a href="#DataspaceSEL">Dataspace Selection.</a></p> + </td> +</tr> + +</table> +</div> + + +<br /> +<br /> +<br /> +<a name="DataspaceSEL"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Dataspace Selection + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Selection Type</td> + </tr> + <tr> + <td colspan="4"><br />Selection Info (<em>variable + size</em>)<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Dataspace Selection + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Selection Type</p></td> + <td> + <p>There are 4 types of selection: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>H5S_SEL_NONE: Nothing selected + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>H5S_SEL_POINTS: Sequence of points selected + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>H5S_SEL_HYPER: Hyperslab selected + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>H5S_SEL_ALL: Entire extent selected + </td> + </tr> + </table> + </td> + + </tr> + + <tr> + <td><p>Selection Info</p></td> + <td> + <p>There are 4 types of selection info: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>Selection info for <a href="#SelNONE">H5S_SEL_NONE</a> + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Selection info for <a href="#SelPOINTS">H5S_SEL_POINTS</a> + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Selection info for <a href="#SelHYPER">H5S_SEL_HYPER</a> + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Selection for <a href="#SelALL">H5S_SEL_ALL</a> + </td> + </tr> + </table> + </td> + + </tr> + </table> + </div> + + + <br /> + <br /> + <br /> +<a name="SelNONE"/></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Selection Info for H5S_SEL_NONE + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Version</td> + </tr> + <tr> + <td colspan="4"><br />Reserved <em>(zero, 8 bytes)</em><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Selection Info for H5S_SEL_NONE + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for the H5S_SEL_NONE Selection Info. + The value is 1.</p></td> + </tr> + </table> + </div> + + + <br /> + <br /> + <br /> + <a name="SelPOINTS"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Selection Info for H5S_SEL_POINTS + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Version</td> + </tr> + <tr> + <td colspan="4"><br /><br />Points Selection Info <em>(variable size)</em> + <br /><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Selection Info for H5S_SEL_POINTS + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for the H5S_SEL_POINTS Selection Info. + The value is either 1 or 2.</p></td> + </tr> + + <tr> + <td><p>Points Selection Info</p></td> + <td><p>Depending on <em>version</em>: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>See <a href="#SelPOINTSV1">Version 1 Points Selection Info</a> + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>See <a href="#SelPOINTSV2">Version 2 Points Selection Info</a> + </td> + </tr> + + </table> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <a name="SelPOINTSV1"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 1 Points Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Reserved <em>(zero)</em></td> + </tr> + + <tr> + <td colspan="4">Length</td> + </tr> + <tr> + <td colspan="4">Rank</td> + </tr> + <tr> + <td colspan="4">Num Points</td> + </tr> + <tr> + <td colspan="4">Point #1: coordinate #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #1: coordinate #u</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #n: coordinate #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #n: coordinate #u</td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 1 Points Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>The size in bytes from <em>Length</em> to the end of the + selection info.</td> + </tr> + + <tr> + <td><p>Rank</p></td> + <td><p>The number of dimensions.</p></td> + </tr> + <tr> + <td><p>Num Points</p></td> + <td><p>The number of points in the selection.</p></td> + </tr> + <tr> + <td><p>Point #n: coordinate #u</p></td> + <td><p>The array of points in the selection. + <p>The points selected are #1 to #n where n is <em>Num Points</em>. + <p>The list of coordinates for each point are #1 to #u where u is + <em>Rank</em>.</p></td> + </tr> + </table> + </div> + + + <br /> + <br /> + <br /> + <a name="SelPOINTSV2"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 2 Points Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="1">Encode Size</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em> + </td> + </tr> + + <tr> + <td colspan="4">Rank</td> + </tr> + <tr> + <td colspan="4">Num Points<p>(2, 4 or 8 bytes)<br /></td> + </tr> + <tr> + <td colspan="4">Point #1: coordinate #1<p>(2, 4 or 8 bytes)<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #1: coordinate #u<p>(2, 4 or 8 bytes)<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #n: coordinate #1 <p>(2, 4 or 8 bytes)<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Point #n: coordinate #u<p>(2, 4 or 8 bytes)<br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 Points Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Encode Size</td> + <td><p>The size for encoding the points selection info which can be 2, 4 or 8 bytes. + </td> + </tr> + + <tr> + <td><p>Rank</p></td> + <td><p>The number of dimensions.</p></td> + </tr> + <tr> + <td><p>Num Points</p></td> + <td><p>The number of points in the selection. + <p>The field <em>Encode Size</em> indicates the size of this field</p></td> + </tr> + <tr> + <td><p>Point #n: coordinate #u</p></td> + <td><p>The array of points in the selection. + <p>The points selected are #1 to #n where n is <em>Num Points</em>. + <p>The list of coordinates for each point are #1 to #u where u is + <em>Rank</em>. + <p>The field <em>Encode Size</em> indicates the size of this field</p></td> + </tr> + </table> + </div> + + + <br /> + <br /> + <br /> + <a name="SelHYPER"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Selection Info for H5S_SEL_HYPER + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Version</td> + </tr> + <tr> + <td colspan="4"><br />Hyperslab Selection Info + (<em>variable size</em>)<br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Selection Info for H5S_SEL_HYPER + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for the H5S_SEL_HYPER selection info. + The value is 1, 2 or 3.</p></td> + </tr> + + <tr> + <td><p>Hyperslab Selection Info</p></td> + <td><p>Depending on <em>version</em>: + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>See <a href="#SelHYPERV1">Version 1 Hyperslab Selection Info</a>. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>See <a href="#SelHYPERV2">Version 2 Hyperslab Selection Info</a> + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>See <a href="#SelHYPERV3">Version 3 Hyperslab Selection Info</a> + </td> + </tr> + </table> + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + <a name="SelHYPERV1"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 1 Hyperslab Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Reserved</td> + </tr> + <tr> + <td colspan="4">Length</td> + </tr> + <tr> + <td colspan="4">Rank</td> + </tr> + <tr> + <td colspan="4">Num Blocks</td> + </tr> + <tr> + <td colspan="4">Starting Offset #1 for Block #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Starting Offset #n for Block #1</td> + </tr> + + <tr> + <td colspan="4">Ending Offset #1 for Block #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Ending Offset #n for Block #1</td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td colspan="4">Starting Offset #1 for Block #u</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Starting Offset #n for Block #u</td> + </tr> + + <tr> + <td colspan="4">Ending Offset #1 for Block #u</em></td> +</tr> +<tr> + <td colspan="4">.<br />.<br />.<br /></td> +</tr> +<tr> + <td colspan="4">Ending Offset #n for Block #u</td> +</tr> + +</table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Version 1 Hyperslab Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>The size in bytes from the field <em>Rank</em> to the + end of the Selection Info.</td> + </tr> + + <tr> + <td><p>Rank</p></td> + <td><p>The number of dimensions in the dataspace.</p></td> + </tr> + + <tr> + <td><p>Num Blocks</p></td> + <td><p>The number of blocks in the selection.</p></td> + </tr> + + <tr> + <td><p>Starting Offset #n for Block #u</p></td> + <td><p>The offset #n of the starting element in block #u. + <p>#n is from 1 to <em>Rank</em>. + <p>#u is from 1 to <em>Num Blocks</em> moving from the fastest + changing dimension to the slowest changing dimension. + </p></td> + </tr> + + <tr> + <td><p>Ending Offset #n for Block #u</p></td> + <td><p>The offset #n of the ending element in block #u. + <p>#n is from 1 to <em>Rank</em>. + <p>#u is from 1 to <em>Num Blocks</em> moving from the fastest + changing dimension to the slowest changing dimension. + </p></td> + </tr> + + </table> +</div> + +<br /> +<br /> +<br /> +<a name="SelHYPERV2"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 2 Hyperslab Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Length</td> + </tr> + <tr> + <td colspan="4">Rank</td> + </tr> + <tr> + <td colspan="4">Start #1 <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Stride #1 <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Count #1 <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Block #1 <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Start #n <em>(8 bytes)</em><p></td> + </tr> + + <tr> + <td colspan="4">Stride #n <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Count #n <em>(8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Block #n <em>(8 bytes)</em><p></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 2 Hyperslab Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is a bit field with the following definition. + Currently, this is always set to 0x1. + <p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>If set, it a a regular hyperslab, otherwise, irregular. + </td> + </tr> + + </table> + </td> + + </tr> + + <tr> + <td><p>Length</p></td> + <td><p>The size in bytes from the field <em>Rank</em> to the + end of the Selection Info.</td> + </tr> + + <tr> + <td><p>Rank</p></td> + <td><p>The number of dimensions in the dataspace.</td> + </tr> + + <tr> + <td><p>Start #n</p></td> + <td><p>The offset of the starting element in the block. + <p>#n is from 1 to <em>Rank</em>. + </p></td> + </tr> + + <tr> + <td><p>Stride #n</p></td> + <td><p>The number of elements to move in each dimension. + <p>#n is from 1 to <em>Rank</em>. + </p></td> + </tr> + + <tr> + <td><p>Count #n</p></td> + <td><p>The number of blocks to select in each dimension. + <p>#n is from 1 to <em>Rank</em>. + </p></td> + </tr> + + <tr> + <td><p>Block #n</p></td> + <td><p>The size (in elements) of each block in each dimension. + <p>#n is from 1 to <em>Rank</em>. + </p></td> + </tr> + </table> + </div> + + + + + <br /> + <br /> + <br /> + <a name="SelHYPERV3"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 3 Hyperslab Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Flags</td> + <td>Encode Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Rank</td> + </tr> + <tr> + <td colspan="4"><br />Regular/Irregular Hyperslab Selection Info + <p><em>(variable size)</em><br /><br/></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 3 Hyperslab Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is a bit field with the following definition: + <p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>If set, it is a regular hyperslab, otherwise, irregular. + </td> + </tr> + + </table> + </td> + </tr> + + <tr> + <td><p>Encode Size</p></td> + <td><p>The size for encoding hyperslab selection info, which can 2, 4 or 8 bytes.</td> + </tr> + + <tr> + <td><p>Rank</p></td> + <td><p>The number of dimensions in the dataspace.</td> + </tr> + + <tr> + <td><p>Regular/Irregular Hyperslab Selection Info</p></td> + <td><p>This is the selection info for version 3 hyperslab which can be regular or irregular. + <p>If bit 0 of the field <em>Flags</em> is set, + See <a href="#SelHYPERV3REG">Version 3 Regular Hyperslab Selection Info</a> + <p>Otherwise, see <a href="#SelHYPERV3IRREG">Version 3 Irregular Hyperslab Selection Info</a> + </td> + + </tr> + + </table> + </div> + + + <br /> + <br /> + <br /> + <a name="SelHYPERV3REG"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 3 Regular Hyperslab Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Start #1 <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Stride #1 <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Count #1 <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Block #1 <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Start #n <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + <tr> + <td colspan="4">Stride #n <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Count #n <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Block #n <p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 3 Regular Hyperslab Selection Info + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Start #n</p></td> + <td><p>The offset of the starting element in the block. + <p>#n is from 1 to <em>Rank</em>. + <p>The field <em>Encode Size</em> indicates the size of this field. + </p></td> + </tr> + + <tr> + <td><p>Stride #n</p></td> + <td><p>The number of elements to move in each dimension. + <p>#n is from 1 to <em>Rank</em>. + <p>The field <em>Encode Size</em> indicates the size of this field. + </p></td> + </tr> + + <tr> + <td><p>Count #n</p></td> + <td><p>The number of blocks to select in each dimension. + <p>#n is from 1 to <em>Rank</em>. + <p>The field <em>Encode Size</em> indicates the size of this field. + </p></td> + </tr> + + <tr> + <td><p>Block #n</p></td> + <td><p>The size (in elements) of each block in each dimension. + <p>#n is from 1 to <em>Rank</em>. + <p>The field <em>Encode Size</em> indicates the size of this field. + </p></td> + </tr> + </table> + </div> + + <br /> + <br /> + <br /> + <a name="SelHYPERV3IRREG"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Version 3 Irregular Hyperslab Selection Info + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Num Blocks<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">Starting Offset #1 for Block #1<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Starting Offset #n for Block #1<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + <tr> + <td colspan="4">Ending Offset #1 for Block #1<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Ending Offset #n for Block #1<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td colspan="4">Starting Offset #1 for Block #u<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Starting Offset #n for Block #u<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + <tr> + <td colspan="4">Ending Offset #1 for Block #u<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Ending Offset #n for Block #u<p><em>(2, 4 or 8 bytes)</em><p></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Version 3 Irregular Hyperslab Selection Info + </caption> + + <tr> + <td><p>Num Blocks</p></td> + <td><p>The number of blocks in the selection. + <p>The field <em>Encode Size</em> indicates the size of this field</p></td> + </tr> + + <tr> + <td><p>Starting Offset #n for Block #u</p></td> + <td><p>The offset #n of the starting element in block #u. + <p>#n is from 1 to <em>Rank</em>. + <p>#u is from 1 to <em>Num Blocks</em> moving from the fastest + changing dimension to the slowest changing dimension. + <p>The field <em>Encode Size</em> indicates the size of this field + </p></td> + </tr> + + <tr> + <td><p>Ending Offset #n for Block #u</p></td> + <td><p>The offset #n of the ending element in block #u. + <p>#n is from 1 to <em>Rank</em>. + <p>#u is from 1 to <em>Num Blocks</em> moving from the fastest + changing dimension to the slowest changing dimension. + <p>The field <em>Encode Size</em> indicates the size of this field + </p></td> + </tr> + + </table> + </div> + + + <br /> + <br /> + <br /> + <a name="SelALL"></a> + <div align="center"> + <table class="format"> + <caption> + Layout: Selection Info for H5S_SEL_ALL + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Version</td> + </tr> + <tr> + <td colspan="4"><br />Reserved <em>(zero, + 8 bytes)</em><br /><br /></td> + </tr> + + </table> + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Selection Info for H5S_SEL_ALL + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for the H5S_SEL_ALL Selection Info; + the value is 1.</p></td> + </tr> + </table> + </div> + + <a name="ReferenceEncodeRV"> + <h3>VIII.B. Reference Encoding (Revised)</h3></a> + <p> + <br /> + For the following reference type, + the Reference Header and Reference Block are stored together as the dataset's raw data: + <ul> + <li>Object Reference (H5R_OBJECT2) (without reference to an external file)</li> + </ul> + <p> + For the following reference types, + the Reference Header plus the <a href="#GlobalHeapID">Global Heap ID</a> are stored + as the dataset's raw data in the file. + The global heap ID is used to locate the Reference Block stored in the global heap: + <ul> + <li>Object Reference (H5R_OBJECT2) (with reference to an external file)</li> + <li>Dataset Region Reference (H5R_DATASET_REGION2) (with/without reference to an external file)</li> + <li>Attribute Reference (H5R_ATTR) (with/without reference to an external file)</li> + </ul> + <br /> + <br /> + + <div align="center"> + <table class="format"> + <caption> + Layout: Reference Header + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Reference Type</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + </table> + + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Reference Header + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Reference Type</p></td> + <td> + <p>There are 3 types of references: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>H5R_OBJECT2: Object Reference + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>H5R_DATASET_REGION2: Dataset Region Reference + </td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>H5R_ATTR: Attribute Reference + </td> + </tr> + + </table> + + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field describes the reference: + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the reference is to an external file. + </td> + </tr> + <tr> + <td align="center"><code>1-7</code></td> + <td>Reserved</td> + </tr> + </table></p> + + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + + <div align="center"> + <table class="format"> + <caption> + Layout: Reference Block + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Token Size</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan=4><br /><br />Token + <em>(variable size)</em><br /> <br /><br /></td> + </tr> + <tr> + <td colspan=2>Length of External File Name</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan=4><br /><br />External File Name + <em>(variable size)</em><br /><br /><br /></td> + </tr> + <tr> + <td colspan=4>Size of Dataspace Selection</td> + </tr> + <tr> + <td colspan=4>Rank of Dataspace Selection</td> + </tr> + <tr> + <td colspan=4><br /><br />Dataspace Selection Information + <em>(variable size)</em><br /><br /> <br /></td> +</td> +</tr> +<tr> + <td colspan=2>Length of Attribute Name </td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> +</tr> +<tr> + <td colspan=4><br /><br />Attribute Name + <em>(variable size)</em><br /><br /><br /></td> +</tr> + +</table> + +</div> + +<br /> +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Reference Block + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Token size</p></td> + <td><p>This is the size of the token for the object. + </td> + </tr> + + <tr> + <td><p>Token</p></td> + <td> + <p> + This is the token for the object. + </p> + </td> + </tr> + + <tr> + <td><p>Length fo External File Name</p></td> + <td><p>This is the length for the external file name. + <p>This field exists if bit 0 of <em>flags</em> is set.</p> + </p> + </td> + </tr> + + <tr> + <td><p>External File Name</p></td> + <td><p>This is the name of the external file being referenced.</p> +</p> +<p>This field exists if bit 0 of <em>flags</em> is set.</p> +</td> +</tr> + +<tr> + <td><p>Dataspace Selection Information</p></td> + <td><p>See <a href="#DataspaceSEL">Dataspace Selection.</a></p> +</p> +<p>This field exists if the <em>Reference Type</em> is H5R_DATASET_REGION2.</p> +</td> +</tr> + +<tr> + <td><p>Length of Attribute Name</p></td> + <td><p>This is the length of the attribute name. + <p>This field exists if the <em>Reference Type</em> is H5R_ATTRIBUTE.</p> + </td> +</tr> + +<tr> + <td><p>Attribute Name</p></td> + <td><p>This is the name of the attribute being referenced. + <p>This field exists if the <em>Reference Type</em> is H5R_ATTRIBUTE.</p> + </td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> + + +<a name="ReferenceEncodeDP"> + <h3>VIII.C. Reference Encoding (Backward Compatibility)</h3></a> +<p> + <br /> + The two references described below are maintained to preserve compatibility with previous versions of the library. +<p> + For the following reference type, + the reference encoding is stored as the dataset's raw data in the file: + <ul> + <li>Object Reference (H5R_OBJECT1)</li> + </ul> +<p> + For the following reference type, + the <a href="#GlobalHeapID">Global Heap ID</a> is stored as the dataset's raw data in the file. + The global heap ID is used to locate the reference encoding + stored in the global heap: + <ul> + <li>Dataset Region Reference (H5R_DATASET_REGION1)</li> + </ul> + + <br /> + <br /> + <div align="center"> + <table class="format"> + <caption> + Layout: Reference for H5R_OBJECT1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Object Address<sup>O</sup><br /><br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> + </table> + + </div> + + <br /> + <br /> + <div align="center"> + <table class="desc"> + <caption> + Fields: Reference for H5R_OBJECT1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Object Address</p></td> + <td> + <p>Address of the object being referenced + </td> + </tr> + + </table> + </div> + + <br /> + <br /> + <br /> + + <div align="center"> + <table class="format"> + <caption> + Layout: Reference for H5R_DATASET_REGION1 + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Object Address<sup>O</sup><br /><br /></td> + </tr> + <tr> + <td colspan=4><br /><br />Dataspace Selection Information + <em>(variable size)</em><br /><br /> <br /></td> +</td> +</tr> + +</table> + +<table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%"> + (Items marked with an ‘O’ in the above table are + of the size specified in the <a href="#SizeOfOffsetsV0">Size + of Offsets</a> field in the superblock.) + </td></tr> +</table> + +</div> + +<br /> +<br /> +<div align="center"> + <table class="desc"> + <caption> + Fields: Reference for H5R_DATASET_REGION1 + </caption> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Object Address</p></td> + <td><p>This is the address of the object being referenced. + </td> + </tr> + + <tr> + <td><p>Dataspace Selection Information</p></td> + <td><p>This is the dataspace selection for the object being referenced. + See <a href="#DataspaceSEL">Dataspace Selection.</a></p> +</p> +</td> +</tr> + +</table> +</div> + +<br /> +<br /> +<br /> + + +</body> +</html> diff --git a/doxygen/examples/H5A_examples.c b/doxygen/examples/H5A_examples.c new file mode 100644 index 0000000..f332efa --- /dev/null +++ b/doxygen/examples/H5A_examples.c @@ -0,0 +1,145 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_acpl, fail_attr, fail_file; + hid_t file, acpl, fspace, attr; + + unsigned mode = H5F_ACC_TRUNC; + char file_name[] = "f1.h5"; + // attribute names can be arbitrary Unicode strings + char attr_name[] = "Χαρακτηριστικό"; + + if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((acpl = H5Pcreate(H5P_ATTRIBUTE_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_acpl; + } + // use UTF-8 encoding for the attribute name + if (H5Pset_char_encoding(acpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // create a scalar (singleton) attribute + if ((fspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // create an attribute on the root group + if ((attr = H5Acreate2(file, attr_name, H5T_STD_I32LE, fspace, acpl, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + + H5Aclose(attr); +fail_attr: + H5Sclose(fspace); +fail_fspace: + H5Pclose(acpl); +fail_acpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_attr, fail_file; + hid_t file, attr; + + unsigned mode = H5F_ACC_RDONLY; + char file_name[] = "f1.h5"; + char attr_name[] = "Χαρακτηριστικό"; + int value; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + // read the attribute value + if (H5Aread(attr, H5T_NATIVE_INT, &value) < 0) + ret_val = EXIT_FAILURE; + + // do something w/ the attribute value + + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_attr, fail_file; + hid_t file, attr; + + unsigned mode = H5F_ACC_RDWR; + char file_name[] = "f1.h5"; + char attr_name[] = "Χαρακτηριστικό"; + int value = 1234; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + // update the attribute value + if (H5Awrite(attr, H5T_NATIVE_INT, &value) < 0) + ret_val = EXIT_FAILURE; + + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_attr, fail_file; + hid_t file; + + unsigned mode = H5F_ACC_RDWR; + char file_name[] = "f1.h5"; + char attr_name[] = "Χαρακτηριστικό"; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // delete the attribute + if (H5Adelete(file, attr_name) < 0) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c new file mode 100644 index 0000000..aad057d --- /dev/null +++ b/doxygen/examples/H5D_examples.c @@ -0,0 +1,173 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_lcpl, fail_dset, fail_file; + hid_t file, lcpl, fspace, dset; + + unsigned mode = H5F_ACC_TRUNC; + char file_name[] = "d1.h5"; + // link names can be arbitrary Unicode strings + char dset_name[] = "σύνολο/δεδομένων"; + + if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + // use UTF-8 encoding for link names + if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // create intermediate groups as needed + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // create a 1D dataspace + if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // create a 32-bit integer dataset + if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dset; + } + + H5Dclose(dset); +fail_dset: + H5Sclose(fspace); +fail_fspace: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dset, fail_file; + hid_t file, dset; + + unsigned mode = H5F_ACC_RDONLY; + char file_name[] = "d1.h5"; + // assume a priori knowledge of dataset name and size + char dset_name[] = "σύνολο/δεδομένων"; + int elts[10]; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dset; + } + // read all dataset elements + if (H5Dread(dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, elts) < 0) + ret_val = EXIT_FAILURE; + + // do something w/ the dataset elements + + H5Dclose(dset); +fail_dset: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_update, fail_fspace, fail_dset, fail_file; + hid_t file, dset, fspace; + + unsigned mode = H5F_ACC_RDWR; + char file_name[] = "d1.h5"; + char dset_name[] = "σύνολο/δεδομένων"; + int new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}}; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dset; + } + // get the dataset's dataspace + if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + // select the first 5 elements in odd positions + if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5}, + NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_update; + } + + // (implicitly) select and write the first 5 elements of the second column of NEW_ELTS + if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0) + ret_val = EXIT_FAILURE; + +fail_update: + H5Sclose(fspace); +fail_fspace: + H5Dclose(dset); +fail_dset: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_delete, fail_file; + hid_t file; + + unsigned mode = H5F_ACC_RDWR; + char file_name[] = "d1.h5"; + char group_name[] = "σύνολο"; + char dset_name[] = "σύνολο/δεδομένων"; + + if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // delete (unlink) the dataset + if (H5Ldelete(file, dset_name, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + // the previous call deletes (unlinks) only the dataset + if (H5Ldelete(file, group_name, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + +fail_delete: + H5Fclose(file); +fail_file:; + } + + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5F_examples.c b/doxygen/examples/H5F_examples.c new file mode 100644 index 0000000..a7ce6fb --- /dev/null +++ b/doxygen/examples/H5F_examples.c @@ -0,0 +1,187 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [life_cycle] --> + { + __label__ fail_fapl, fail_fcpl, fail_file; + hid_t fcpl, fapl, file; + + if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fcpl; + } + else { + // adjust the file creation properties + } + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } + else { + // adjust the file access properties + } + + unsigned mode = H5F_ACC_EXCL; + char name[] = "f1.h5"; + + if ((file = H5Fcreate(name, mode, fcpl, fapl)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // do something useful with FILE + + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl: + H5Pclose(fcpl); +fail_fcpl:; + } + //! <!-- [life_cycle] --> + + //! <!-- [life_cycle_w_open] --> + { + __label__ fail_fapl, fail_file; + hid_t fapl, file; + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } + else { + // adjust the file access properties + } + + unsigned mode = H5F_ACC_RDWR; + char name[] = "f1.h5"; + + if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // do something useful with FILE + + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl:; + } + //! <!-- [life_cycle_w_open] --> + + //! <!-- [minimal] --> + { + unsigned mode = H5F_ACC_TRUNC; + char name[] = "f11.h5"; + + hid_t file = H5Fcreate(name, mode, H5P_DEFAULT, H5P_DEFAULT); + if (file != H5I_INVALID_HID) + H5Fclose(file); + else + ret_val = EXIT_FAILURE; + } + //! <!-- [minimal] --> + + //! <!-- [open] --> + { + unsigned mode = H5F_ACC_RDONLY; + char name[] = "f11.h5"; + + hid_t file = H5Fopen(name, mode, H5P_DEFAULT); + if (file != H5I_INVALID_HID) + H5Fclose(file); + else + ret_val = EXIT_FAILURE; + } + //! <!-- [open] --> + + //! <!-- [flush] --> + { + unsigned mode = H5F_ACC_RDWR; + char name[] = "f11.h5"; + + hid_t file = H5Fopen(name, mode, H5P_DEFAULT); + if (file != H5I_INVALID_HID) { + int step; + for (step = 0; step < 1000; ++step) { + + // do important work & flush every 20 steps + + if (step % 20 == 0) { + if (H5Fflush(file, H5F_SCOPE_LOCAL) < 0) { + perror("H5Fflush failed."); + ret_val = EXIT_FAILURE; + break; + } + } + } + + if (H5Fclose(file) < 0) + perror("H5Fclose failed."); + } + else + ret_val = EXIT_FAILURE; + } + //! <!-- [flush] --> + + //! <!-- [libver_bounds] --> + { + unsigned mode = H5F_ACC_RDWR; + char name[] = "f11.h5"; + + hid_t file = H5Fopen(name, mode, H5P_DEFAULT); + if (file != H5I_INVALID_HID) { + if (H5Fset_libver_bounds(file, H5F_LIBVER_EARLIEST, H5F_LIBVER_V18) >= 0) { + + // object creation will not exceed HDF5 version 1.8.x + } + else + perror("H5Fset_libver_bounds failed."); + + if (H5Fclose(file) < 0) + perror("H5Fclose failed."); + } + else + ret_val = EXIT_FAILURE; + } + //! <!-- [libver_bounds] --> + + //! <!-- [mount] --> + { + hid_t file = H5Fopen("f11.h5", H5F_ACC_RDWR, H5P_DEFAULT); + if (file != H5I_INVALID_HID) { + hid_t group, child; + if ((group = H5Gcreate1(file, "mount_point", H5P_DEFAULT)) != H5I_INVALID_HID) { + if ((child = H5Fopen("f1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) != H5I_INVALID_HID) { + if (H5Fmount(group, ".", child, H5P_DEFAULT) >= 0) { + + // do something useful w/ the mounted file + } + else { + ret_val = EXIT_FAILURE; + perror("H5Fmount failed."); + } + H5Fclose(child); + } + H5Gclose(group); + } + H5Fclose(file); + } + else + ret_val = EXIT_FAILURE; + } + //! <!-- [mount] --> + + return ret_val; +} diff --git a/doxygen/examples/H5Pget_metadata_read_attempts.1.c b/doxygen/examples/H5Pget_metadata_read_attempts.1.c new file mode 100644 index 0000000..da325c0 --- /dev/null +++ b/doxygen/examples/H5Pget_metadata_read_attempts.1.c @@ -0,0 +1,22 @@ +/* Get a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Retrieve the # of read attempts from the file access property list */ +H5Pget_metadata_read_attempts(fapl, &attempts); + +/* + * The value returned in "attempts" will be 1 (default for non-SWMR access). + */ + +/* Set the # of read attempts to 20 */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Retrieve the # of read attempts from the file access property list */ +H5Pget_metadata_read_attempts(fapl, &attempts); + +/* + * The value returned in "attempts" will be 20 as set. + */ + +/* Close the property list */ +H5Pclose(fapl); diff --git a/doxygen/examples/H5Pget_metadata_read_attempts.2.c b/doxygen/examples/H5Pget_metadata_read_attempts.2.c new file mode 100644 index 0000000..2cd12db --- /dev/null +++ b/doxygen/examples/H5Pget_metadata_read_attempts.2.c @@ -0,0 +1,44 @@ +/* Open the file with SWMR access and default file access property list */ +fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), H5P_DEFAULT); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 100 (default for SWMR access). + */ + +/* Close the property list */ +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); + +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 20. + */ + +/* Close the property lists */ +H5Pclose(file_fapl); +H5Pclose(fapl); + +/* Close the file */ +H5Fclose(fid); diff --git a/doxygen/examples/H5Pget_metadata_read_attempts.3.c b/doxygen/examples/H5Pget_metadata_read_attempts.3.c new file mode 100644 index 0000000..4b5ea3a --- /dev/null +++ b/doxygen/examples/H5Pget_metadata_read_attempts.3.c @@ -0,0 +1,44 @@ +/* Open the file with non-SWMR access and default file access property list */ +fid = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 1 (default for non-SWMR access). + */ + +/* Close the property list */ +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); + +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with non-SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 1 (default for non-SWMR access). + */ + +/* Close the property lists */ +H5Pclose(file_fapl); +H5Pclose(fapl); + +/* Close the file */ +H5Fclose(fid); diff --git a/doxygen/examples/H5Pget_object_flush_cb.c b/doxygen/examples/H5Pget_object_flush_cb.c new file mode 100644 index 0000000..d18f3df --- /dev/null +++ b/doxygen/examples/H5Pget_object_flush_cb.c @@ -0,0 +1,41 @@ +hid_t fapl_id; +unsigned counter; +H5F_object_flush_t *ret_cb; +unsigned * ret_counter; + +/* Create a copy of the file access property list */ +fapl_id = H5Pcreate(H5P_FILE_ACCESS); + +/* Set up the object flush property values */ +/* flush_cb: callback function to invoke when an object flushes (see below) */ +/* counter: user data to pass along to the callback function */ +H5Pset_object_flush_cb(fapl_id, flush_cb, &counter); + +/* Open the file */ +file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + +/* Get the file access property list for the file */ +fapl = H5Fget_access_plist(file_id); + +/* Retrieve the object flush property values for the file */ +H5Pget_object_flush_cb(fapl, &ret_cb, &ret_counter); +/* ret_cb will point to flush_cb() */ +/* ret_counter will point to counter */ + +/* +. +. +. +. +. +. +*/ + +/* The callback function for the object flush property */ +static herr_t +flush_cb(hid_t obj_id, void *_udata) +{ + unsigned *flush_ct = (unsigned *)_udata; + ++(*flush_ct); + return 0; +} diff --git a/doxygen/examples/H5Pset_metadata_read_attempts.c b/doxygen/examples/H5Pset_metadata_read_attempts.c new file mode 100644 index 0000000..7c2f65d --- /dev/null +++ b/doxygen/examples/H5Pset_metadata_read_attempts.c @@ -0,0 +1,59 @@ +//! [SWMR Access] +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 20. + * The library will use 20 as the number of read attempts + * when reading checksummed metadata in the file + */ + +/* Close the property list */ +H5Pclose(fapl); +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); +//! [SWMR Access] + +//! [non-SWMR Access] +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 1 (default for non-SWMR access). + * The library will use 1 as the number of read attempts + * when reading checksummed metadata in the file + */ + +/* Close the property lists */ +H5Pclose(fapl); +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); +//! [non-SWMR Access] diff --git a/doxygen/examples/H5Pset_object_flush_cb.c b/doxygen/examples/H5Pset_object_flush_cb.c new file mode 100644 index 0000000..1dfa90d --- /dev/null +++ b/doxygen/examples/H5Pset_object_flush_cb.c @@ -0,0 +1,41 @@ +hid_t file_id, fapl_id; +hid_t dataset_id, dapl_id; +unsigned counter; + +/* Create a copy of the file access property list */ +fapl_id = H5Pcreate(H5P_FILE_ACCESS); + +/* Set up the object flush property values */ +/* flush_cb: callback function to invoke when an object flushes (see below) */ +/* counter: user data to pass along to the callback function */ +H5Pset_object_flush_cb(fapl_id, flush_cb, &counter); + +/* Open the file */ +file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + +/* Create a group */ +gid = H5Gcreate2(fid, “group”, H5P_DEFAULT, H5P_DEFAULT_H5P_DEFAULT); + +/* Open a dataset */ +dataset_id = H5Dopen2(file_id, DATASET, H5P_DEFAULT); + +/* The flush will invoke flush_cb() with counter */ +H5Dflush(dataset_id); +/* counter will be equal to 1 */ + +/* ... */ + +/* The flush will invoke flush_cb() with counter */ +H5Gflush(gid); +/* counter will be equal to 2 */ + +/* ... */ + +/* The callback function for object flush property */ +static herr_t +flush_cb(hid_t obj_id, void *_udata) +{ + unsigned *flush_ct = (unsigned *)_udata; + ++(*flush_ct); + return 0; +} diff --git a/doxygen/examples/ImageSpec.html b/doxygen/examples/ImageSpec.html new file mode 100644 index 0000000..1b700ff --- /dev/null +++ b/doxygen/examples/ImageSpec.html @@ -0,0 +1,1203 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.72 [en] (WinNT; U) [Netscape]"> + <title>Image Specification</title> + +The HDF5 specification defines the standard objects and storage for the +standard HDF5 objects. (For information about the HDF5 library, model and +specification, see the HDF documentation.) This document is an additional +specification do define a standard profile for how to store image data +in HDF5. Image data in HDF5 is stored as HDF5 datasets with standard attributes +to define the properties of the image. +<p>This specification is primarily concerned with two dimensional raster +data similar to HDF4 Raster Images. Specifications for storing other +types of imagery will be covered in other documents. +<p>This specification defines: +<ul> +<li> +Standard storage and attributes for an Image dataset (<a href="#Sect1">Section +1</a>)</li> + +<li> +Standard storage and attributes for Palettes (<a href="#sect2">Section +2</a>)</li> + +<li> +Standard for associating Palettes with Images. (<a href="#Sect3">Section +3</a>)</li> +</ul> + +<h2> +<a NAME="Sect1"></a>1. HDF5 Image Specification</h2> + +<h3> +1.1 Overview</h3> +Image data is stored as an HDF5 dataset with values of HDF5 class Integer +or Float. A common example would be a two dimensional dataset, with +elements of class Integer, e.g., a two dimensional array of unsigned 8 +bit integers. However, this specification does not limit the dimensions +or number type that may be used for an Image. +<p>The dataset for an image is distinguished from other datasets by giving +it an attribute "CLASS=IMAGE". In addition, the Image dataset may +have an optional attribute "PALETTE" that is an array of object references +for zero or more palettes. The Image dataset may have additional attributes +to describe the image data, as defined in <a href="#Sect1.2">Section 1.2</a>. +<p>A Palette is an HDF5 dataset which contains color map information. +A Pallet dataset has an attribute "CLASS=PALETTE" and other attributes +indicating the type and size of the palette, as defined in <a href="#sect2">Section +2.1</a>. A Palette is an independent object, which can be shared +among several Image datasets. +<h3> +<a NAME="Sect1.2"></a>1.2 Image Attributes</h3> +The attributes for the Image are scalars unless otherwise noted. +The length of String valued attributes should be at least the number of +characters. Optionally, String valued attributes may be stored in a String +longer than the minimum, in which case it must be zero terminated or null +padded. "Required" attributes must always be used. "Optional" attributes +must be used when required. +<br> +<h4> +Attributes</h4> + +<dl> +<dt> +Attribute name="<b>CLASS</b>" (Required)</dt> + +<dd> +This attribute is type H5T_C_S1, with size 5.</dd> + +<dd> +For all Images, the value of this attribute is "IMAGE".</dd> + +<dd> +</dd> + +<dd> +This attribute identifies this data set as intended to be interpreted as +an image that conforms to the specifications on this page.</dd> +</dl> + +<dt> +Attribute name="<b>PALETTE</b>"</dt> + +<dl> +<dd> +A Image dataset within an HDF5 file may optionally specify an array of +palettes to be viewed with. The dataset will have an attribute field called +"<b>PALETTE</b>" which contains a one-dimensional array of object reference +pointers (HDF5 datatype H5T_STD_REF_OBJ) which refer to palettes in the +file. The palette datasets must conform to the Palette specification in +<a href="#sect2">section +2 below</a>. The first palette in this array will be the default palette +that the data may be viewed with.</dd> +</dl> + +<dl> +<dt> +</dt> + +<dt> +Attribute name="<b>IMAGE_SUBCLASS</b>"</dt> + +<dd> +If present, the value of this attribute indicates the type of Palette that +should be used with the Image. This attribute is a scalar of type +H5T_C_S1, with size according to the string plus one. The values +are:</dd> + +<dl> +<dt> +"IMAGE_GRAYSCALE" (length 15)</dt> + +<dd> +A grayscale image</dd> + +<dt> +"IMAGE_BITMAP" (length 12)</dt> + +<dd> +A bit map image</dd> + +<dt> +"IMAGE_TRUECOLOR" (length 15)</dt> + +<dd> +A truecolor image</dd> + +<dt> +"IMAGE_INDEXED" (length 13)</dt> + +<dd> +An indexed image</dd> + +<dd> +</dd> +</dl> + +<dt> +Attribute name="<b>INTERLACE_MODE</b>"</dt> + +<dd> +For images with more than one component for each pixel, this optional attribute +specifies the layout of the data. The values are type H5T_C_S1 of length +15. See <a href="#Section1.3">section 1.3</a> for information about the +storage layout for data.</dd> + +<dd> +"INTERLACE_PIXEL" (default): the component value for a pixel are contiguous.</dd> + +<dd> +"INTERLACE_PLANE": each component is stored as a plane.</dd> + +<dt> +</dt> + +<dt> +Attribute name="<b>DISPLAY_ORIGIN</b>"</dt> + +<dd> +This optional attribute indicates the intended orientation of the data +on a two-dimensional raster display. The value indicates which corner +the pixel at (0, 0) should be viewed. The values are type H5T_C_S1 +of length 2. If DISPLAY_ORIGIN is not set, the orientation is undefined.</dd> + +<dd> +"UL": (0,0) is at the upper left.</dd> + +<dd> +"LL": (0,0) is at the lower left.</dd> + +<dd> +"UR": (0,0) is at the upper right.</dd> + +<dd> +"LR": (0,0) is at the lower right.</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_WHITE_IS_ZERO</b>"</dt> + +<dl> +<dd> +This attribute is of type H5T_NATIVE_UCHAR. 0 = false, 1 = true . +This is used for images with IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".</dd> +</dl> + +<dl> +<dt> +Attribute name="<b>IMAGE_MINMAXRANGE</b>"</dt> + +<dd> +If present, this attribute is an array of two numbers, of the same HDF5 +datatype as the data. The first element is the minimum value of the +data, and the second is the maximum. This is used for images with +IMAGE_SUBCLASS="IMAGE_GRAYSCALE", "IMAGE_BITMAP" or "IMAGE_INDEXED".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_BACKGROUNDINDEX</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the index value that should be interpreted +as the "background color". This attribute is HDF5 type H5T_NATIVE_UINT.</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_TRANSPARENCY</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the index value that should be interpreted +as the "transparent color". This attribute is HDF5 type H5T_NATIVE_UINT. +This attribute may not be used for IMAGE_SUBCLASS="IMAGE_TRUE_COLOR".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_ASPECTRATIO</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the aspect ratio.</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_COLORMODEL</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the color model of Palette that should +be used with the Image. This attribute is of type H5T_C_S1, with +size 3, 4, or 5. The value is one of the color models described in +the Palette specification in <a href="#sect2.2">section 2.2 below</a>. +This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or +"IMAGE_INDEXED".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_GAMMACORRECTION</b>"</dt> + +<dl> +<dd> +If set, this attribute gives the Gamma correction. The attribute +is type H5T_NATIVE_FLOAT. This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" +or "IMAGE_INDEXED".</dd> +</dl> +Attribute name="<b>IMAGE_VERSION</b>" (Required) +<dl> +<dd> +This attribute is of type H5T_C_S1, with size corresponding to the length +of the version string. This attribute identifies the version number +of this specification to which it conforms. The current version number +is "1.2".</dd> + +<br> +<p> +<br> +<br> +<center><table BORDER=2 BGCOLOR="#FFFFFF" > +<caption><b>Table 1. Attributes of an Image Dataset</b></caption> + +<tr> +<td><b>Attribute Name</b></td> + +<td><b>(R = Required</b> +<br><b>O= Optional)</b></td> + +<td><b>Type</b></td> + +<td><b>String Size</b></td> + +<td><b>Value</b></td> +</tr> + +<tr> +<td>CLASS</td> + +<td>R</td> + +<td>String</td> + +<td>5</td> + +<td>"IMAGE"</td> +</tr> + +<tr> +<td>PALETTE</td> + +<td>O</td> + +<td>Array Object References</td> + +<td></td> + +<td><references to Palette datasets><sup>1</sup></td> +</tr> + +<tr> +<td>IMAGE_SUBCLASS</td> + +<td>O<sup>2</sup></td> + +<td>String</td> + +<td>15, +<br>12, +<br>15, +<br>13</td> + +<td> +<dt> +"IMAGE_GRAYSCALE",</dt> + +<dt> +"IMAGE_BITMAP",</dt> + +<dt> +"IMAGE_TRUECOLOR",</dt> + +<dt> +"IMAGE_INDEXED"</dt> +</td> +</tr> + +<tr> +<td>INTERLACE_MODE</td> + +<td>O<sup>3,6</sup></td> + +<td>String</td> + +<td>15</td> + +<td>The layout of components if more than one component per pixel.</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> + +<td>O</td> + +<td>String</td> + +<td>2</td> + +<td>If set, indicates the intended location of the pixel (0,0).</td> +</tr> + +<tr> +<td>IMAGE_WHITE_IS_ZERO</td> + +<td>O<sup>3,4</sup></td> + +<td>Unsigned Integer</td> + +<td></td> + +<td>0 = false, 1 = true</td> +</tr> + +<tr> +<td>IMAGE_MINMAXRANGE</td> + +<td>O<sup>3,5</sup></td> + +<td>Array [2] <same datatype as data values></td> + +<td></td> + +<td>The (<minimum>, <maximum>) value of the data.</td> +</tr> + +<tr> +<td>IMAGE_BACKGROUNDINDEX</td> + +<td>O<sup>3</sup></td> + +<td>Unsigned Integer</td> + +<td></td> + +<td>The index of the background color.</td> +</tr> + +<tr> +<td>IMAGE_TRANSPARENCY</td> + +<td>O<sup>3,5</sup></td> + +<td>Unsigned Integer</td> + +<td></td> + +<td>The index of the transparent color.</td> +</tr> + +<tr> +<td>IMAGE_ASPECTRATIO</td> + +<td>O<sup>3,4</sup></td> + +<td>Unsigned Integer</td> + +<td></td> + +<td>The aspect ratio.</td> +</tr> + +<tr> +<td>IMAGE_COLORMODEL</td> + +<td>O<sup>3,6</sup></td> + +<td>String</td> + +<td>3, 4, or 5</td> + +<td>The color model, as defined below in the Palette specification for +attribute <b>PAL_COLORMODEL</b>.</td> +</tr> + +<tr> +<td>IMAGE_GAMMACORRECTION</td> + +<td>O<sup>3,6</sup></td> + +<td>Float</td> + +<td></td> + +<td>The gamma correction.</td> +</tr> + +<tr> +<td>IMAGE_VERSION</td> + +<td>R</td> + +<td>String</td> + +<td>3</td> + +<td>"1.2"</td> +</tr> +</table></center> + +<dl><font size=-1>1. The first element of the array is the default +Palette.</font> +<br><font size=-1>2. This attribute is <b>required</b> for images +that use one of the standard color map types listed.</font> +<br><font size=-1>3. This attribute is <b>required</b> if set for the source +image, in the case that the image is translated from another file into +HDF5.</font> +<br><font size=-1>4. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE" +or "IMAGE_BITMAP".</font> +<br><font size=-1>5. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE", +"IMAGE_BITMAP", or "IMAGE_INDEXED".</font> +<br><font size=-1>6. This applies to: IMAGE_SUBCLASS="IMAGE_TRUECOLOR", +or "IMAGE_INDEXED".</font></dl> +</dl> +Table 2 summarizes the standard attributes for an Image datasets using +the common sub-classes. R means that the attribute listed on the leftmost +column is Required for the image subclass on the first row, O means that +the attribute is Optional for that subclass and N that the attribute cannot +be applied to that subclass. The two first rows show the only required +attributes +for all subclasses. +<br> +<table BORDER WIDTH="100%" > +<caption><b>Table 2a. Applicability of Attributes to IMAGE sub-classes</b></caption> + +<tr> +<td WIDTH="20%"><b>IMAGE_SUBCLASS</b><sup>1</sup></td> + +<td WIDTH="20%"><b>IMAGE_GRAYSCALE</b></td> + +<td WIDTH="20%"><b>IMAGE_BITMAP</b></td> +</tr> + +<tr> +<td WIDTH="20%">CLASS</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_VERSION</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td>INTERLACE_MODE</td> + +<td>N</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_MINMAXRANGE</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_TRANSPARENCY</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_ASPECTRATIO</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_COLORMODEL</td> + +<td WIDTH="20%">N</td> + +<td WIDTH="20%">N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_GAMMACORRECTION</td> + +<td WIDTH="20%">N</td> + +<td WIDTH="20%">N</td> +</tr> + +<tr> +<td WIDTH="20%">PALETTE</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> + +<td>O</td> + +<td>O</td> +</tr> +</table> + +<blockquote> </blockquote> + +<table BORDER WIDTH="100%" > +<caption><b>Table 2b. Applicability of Attributes to IMAGE sub-classes</b></caption> + +<tr> +<td WIDTH="20%"><b>IMAGE_SUBCLASS</b></td> + +<td WIDTH="20%"><b>IMAGE_TRUECOLOR</b></td> + +<td><b>IMAGE_INDEXED</b></td> +</tr> + +<tr> +<td WIDTH="20%">CLASS</td> + +<td WIDTH="20%">R</td> + +<td>R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_VERSION</td> + +<td WIDTH="20%">R</td> + +<td>R</td> +</tr> + +<tr> +<td>INTERLACE_MODE</td> + +<td>R</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td> + +<td WIDTH="20%">N</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_MINMAXRANGE</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_TRANSPARENCY</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_ASPECTRATIO</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_COLORMODEL</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_GAMMACORRECTION</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">PALETTE</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> + +<td>O</td> + +<td>O</td> +</tr> +</table> + +<h3> +<a NAME="Section1.3"></a>1.3 Storage Layout and Properties for Images</h3> +In the case of an image with more than one component per pixel (e.g., Red, +Green, and Blue), the data may be arranged in one of two ways. Following +HDF4 terminology, the data may be interlaced by pixel or by plane, which +should be indicated by the INTERLACE_MODE attribute. In both +cases, the dataset will have a dataspace with three dimensions, height, +width, and components. The interlace modes specify different orders +for the dimensions. +<br> +<table BORDER COLS=2 WIDTH="100%" > +<caption><b>Table 3. Storage of multiple component image data.</b></caption> + +<tr> +<td><b>Interlace Mode</b></td> + +<td><b>Dimensions in the Dataspace</b></td> +</tr> + +<tr> +<td>INTERLACE_PIXEL</td> + +<td>[height][width][pixel components]</td> +</tr> + +<tr> +<td>INTERLACE_PLANE</td> + +<td>[pixel components][height][width]</td> +</tr> +</table> + +<p>For example, consider a 5 (rows) by 10 (column) image, with Red, Green, +and Blue components. Each component is an unsigned byte. In HDF5, +the datatype would be declared as an unsigned 8 bit integer. For +pixel interlace, the dataspace would be a three dimensional array, with +dimensions: [10][5][3]. For plane interleave, the dataspace would +be three dimensions: [3][10][5]. +<p>In the case of images with only one component, the dataspace may be +either a two dimensional array, or a three dimensional array with the third +dimension of size 1. For example, a 5 by 10 image with 8 bit color +indexes would be an HDF5 dataset with type unsigned 8 bit integer. +The dataspace could be either a two dimensional array, with dimensions +[10][5], or three dimensions, with dimensions either [10][5][1] or [1][10][5]. +<p>Image datasets may be stored with any chunking or compression properties +supported by HDF5. +<p><b>A note concerning compatibility with HDF5 GR interface: </b>An Image +dataset is stored as an HDF5 dataset. It is important to note that +the order of the dimensions is the same as for any other HDF5 dataset. +For a two dimensional image that is to be stored as a series of horizontal +scan lines, with the scan lines contiguous (i.e., the fastest changing +dimension is 'width'), the image will have a dataspace with <i>dim[0] = +height</i> and <i>dim[1]</i> = <i>width</i>. This is completely consistent +with all other HDF5 datasets. +<p>Users familiar with HDF4 should be cautioned that <i>this is not the +same as HDF4</i>, and specifically is not consistent with what the HDF4 +GR interface does. +<br> +<h2> +<a NAME="sect2"></a>2. HDF5 Palette Specification</h2> + +<h3> +2.1 Overview</h3> +A palette is the means by which color is applied to an image and is also +referred to as a color lookup table. It is a table in which every row contains +the numerical representation of a particular color. In the example of an +8 bit standard RGB color model palette, this numerical representation of +a color is presented as a triplet specifying the intensity of red, green, +and blue components that make up each color. +<center> +<p><img SRC="Palettes.fm.anc.gif" ></center> + +<p>In this example, the color component numeric type is an 8 bit unsigned +integer. While this is most common and recommended for general use, other +component color numeric datatypes, such as a 16 bit unsigned integer , +may be used. This type is specified as the type attribute of the palette +dataset. (see H5Tget_type(), H5Tset_type()) +<p>The minimum and maximum values of the component color numeric are specified +as attribute of the palette dataset. See below (attribute PAL_MINMAXNUMERIC). +If these attributes do not exist, it is assumed that the range of values +will fill the space of the color numeric type. i.e. with an 8 bit unsigned +integer, the valid range would be 0 to 255 for each color component. +<p>The HDF5 palette specification additionally allows for color models +beyond RGB. YUV, HSV, CMY, CMYK, YCbCr color models are supported, and +may be specified as a color model attribute of the palette dataset. <i>(see +"Palette Attributes" for details)</i>. +<p>In HDF 4 and earlier, palettes were limited to 256 colors. The HDF5 +palette specification allows for palettes of varying length. The length +is specified as the number of rows of the palette dataset. +<br> +<br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#666666" > +<tr> +<td><font color="#FFFFFF">Important Note: The specification of the Indexed +Palette will change substantially in the next version. The Palette +described here is <i>denigrated</i> and is not supported.</font></td> +</tr> +</table> + +<br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> +<p>In a standard palette, the color entries are indexed directly. HDF5 +supports the notion of a range index table. Such a table defines an ascending +ordered list of ranges that map dataset values to the palette. If a range +index table exists for the palette, the PAL_TYPE attribute will be set +to "RANGEINDEX", and the PAL_RANGEINDEX attribute will contain an object +reference to a range index table array. If not, the PAL_TYPE attribute +either does not exist, or will be set to "STANDARD". +<p>The range index table array consists of a one dimensional array with +the same length as the palette dataset - 1. Ideally, the range index would +be of the same type as the dataset it refers to, however this is not a +requirement. +<p><b>Example 2: A range index array of type floating point</b> +<center> +<p><img SRC="PaletteExample1.gif" ></center> + +<p>The range index array attribute defines the "<i>to</i>" of the range. +Notice that the range index array attribute is one less entry in size than +the palette. The first entry of 0.1259, specifies that all values below +and up to 0.1259 inclusive, will map to the first palette entry. The second +entry signifies that all values greater than 0.1259 up to 0.3278 inclusive, +will map to the second palette entry, etc. All value greater than the last +range index array attribute (100000) map to the last entry in the palette.</td> +</tr> +</table> + +<h3> +<a NAME="sect2.2"></a>2.2. Palette Attributes</h3> +A palette exists in an HDF file as an independent data set with accompanying +attributes. The Palette attributes are scalars except where noted +otherwise. String values should have size the length of the string +value plus one. "Required" attributes must be used. "Optional" +attributes must be used when required. +<p>These attributes are defined as follows: +<dl> +<dt> +Attribute name="<b>CLASS</b>" (Required)</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 7.</dd> + +<dd> +For all palettes, the value of this attribute is "PALETTE". This attribute +identifies this palette data set as a palette that conforms to the specifications +on this page.</dd> + +<dt> +Attribute name="<b>PAL_COLORMODEL</b>" (Required)</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 3, 4, or 5.</dd> + +<dd> +Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".</dd> + +<dd> +This defines the color model that the entries in the palette data set represent.</dd> + +<dl> +<dt> +"RGB"</dt> + +<dd> +Each color index contains a triplet where the the first value defines the +red component, second defines the green component, and the third the blue +component.</dd> + +<dt> +"CMY"</dt> + +<dd> +Each color index contains a triplet where the the first value defines the +cyan component, second defines the magenta component, and the third the +yellow component.</dd> + +<dt> +"CMYK"</dt> + +<dd> +Each color index contains a quadruplet where the the first value defines +the cyan component, second defines the magenta component, the third the +yellow component, and the forth the black component.</dd> + +<dt> +"YCbCr"</dt> + +<dd> +Class Y encoding model. Each color index contains a triplet where the the +first value defines the luminance, second defines the Cb Chromonance, and +the third the Cr Chromonance.</dd> + +<dt> +"YUV"</dt> + +<dd> +Composite encoding color model. Each color index contains a triplet where +the the first value defines the luminance component, second defines the +chromonance component, and the third the value component.</dd> + +<dt> +"HSV"</dt> + +<dd> +Each color index contains a triplet where the the first value defines the +hue component, second defines the saturation component, and the third the +value component. The hue component defines the hue spectrum with a low +value representing magenta/red progressing to a high value which would +represent blue/magenta, passing through yellow, green, cyan. A low value +for the saturation component means less color saturation than a high value. +A low value for <i>value</i> will be darker than a high value.</dd> + +<dd> +</dd> +</dl> + +<dt> +Attribute name="<b>PAL_TYPE</b>" (Required)</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 9 or 10.</dd> + +<dd> +The current supported values for this attribute are : "STANDARD8" or "RANGEINDEX"</dd> + +<dd> +A PAL_TYPE of "STANDARD8" defines a palette dataset such that the first +entry defines index 0, the second entry defines index 1, etc. up until +the length of the palette - 1. This assumes an image dataset with direct +indexes into the palette.</dd> +</dl> + +<dl> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> +<p>If the PAL_TYPE is set to "RANGEINDEX", there will be an additional +attribute with a name of "<b>PAL_RANGEINDEX</b>", (See example 2 +for more details)</td> +</tr> +</table> + +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td> +<dt> +Attribute name="<b>PAL_RANGEINDEX</b>" <i>(Denigrated)</i></dt> + +<dl> +<dd> +The <b>PAL_RANGEINDEX</b> attribute contains an HDF object reference (HDF5 +datatype H5T_STD_REF_OBJ) pointer which specifies a range index array in +the file to be used for color lookups for the palette. (Only for +PAL_TYPE="RANGEINDEX")</dd> +</dl> +</td> +</tr> +</table> + +<dt> +Attribute name="<b>PAL_MINMAXNUMERIC</b>"</dt> + +<dl> +<dt> +If present, this attribute is an array of two numbers, of the same HDF5 +datatype as the palette elements or color numerics.</dt> + +<br>They specify the minimum and maximum values of the color numeric components. +For example, if the palette was an RGB of type Float, the color numeric +range for Red, Green, and Blue could be set to be between 0.0 and 1.0. +The intensity of the color guns would then be scaled accordingly to be +between this minimum and maximum attribute.</dl> +Attribute name="<b>PAL_VERSION</b>" (Required) +<dl>This attribute is of type H5T_C_S1, with size corresponding to the +length of the version string. This attribute identifies the version +number of this specification to which it conforms. The current version +is "1.2".</dl> + +<center><table BORDER=2 BGCOLOR="#FFFFFF" > +<caption><b>Table 4. Attributes of a Palette Dataset</b></caption> + +<tr> +<td><b>Attribute Name</b></td> + +<td><b>(R = Required,</b> +<br><b>O = Optional)</b></td> + +<td><b>Type</b></td> + +<td><b>String Size</b></td> + +<td><b>Value</b></td> +</tr> + +<tr> +<td>CLASS</td> + +<td>R</td> + +<td>String</td> + +<td> +<center>7</center> +</td> + +<td>"PALETTE"</td> +</tr> + +<tr> +<td>PAL_COLORMODEL</td> + +<td>R</td> + +<td>String</td> + +<td> +<center>3, 4, or 5</center> +</td> + +<td>Color Model: "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"</td> +</tr> + +<tr> +<td>PAL_TYPE</td> + +<td>R</td> + +<td>String</td> + +<td> +<center>9</center> + +<p><br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td>or 10</td> +</tr> +</table> +</td> + +<td>"STANDARD8" +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td>or "RANGEINDEX" <i>(Denigrated)</i></td> +</tr> +</table> +</td> +</tr> + +<tr> +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> +<br>RANGE_INDEX</td> +</tr> +</table> +</td> + +<td></td> + +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td>Object Reference </td> +</tr> +</table> +</td> + +<td></td> + +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><Object Reference to Dataset of range index values></td> +</tr> +</table> +</td> +</tr> + +<tr> +<td>PAL_MINMAXNUMERIC</td> + +<td>O</td> + +<td>Array[2] of <same datatype as palette></td> + +<td></td> + +<td>The first value is the <Minimum value for color values>, the second +value is <Maximum value for color values><sup>2</sup></td> +</tr> + +<tr> +<td>PAL_VERSION</td> + +<td>R</td> + +<td>String</td> + +<td>4</td> + +<td>"1.2"</td> +</tr> +</table></center> + +<dl> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><font size=-1>1. The RANGE_INDEX attribute is required if the +PAL_TYPE is "RANGEINDEX". Otherwise, the RANGE_INDEX attribute should +be omitted. (Range index is denigrated.)</font></td> +</tr> +</table> +<font size=-1>2. The minimum and maximum are optional. If not +set, the range is assumed to the maximum range of the number type. +If one of these attributes is set, then both should be set. The value +of the minimum must be less than or equal to the value of the maximum.</font></dl> +</dl> +Table 5 summarized the uses of the standard attributes for a palette dataset. +R means that the attribute listed on the leftmost column is Required for +the palette type on the first row, O means that the attribute is Optional +for that type and N that the attribute cannot be applied to that type. +The four first rows show the attributes that are always required +for the two palette types. +<br> +<br> +<table BORDER WIDTH="100%" > +<caption><b>Table 5. Applicability of Attributes</b></caption> + +<tr> +<td WIDTH="33%"><b>PAL_TYPE</b></td> + +<td WIDTH="33%"><b>STANDARD8</b></td> + +<td WIDTH="34%"><b>RANGEINDEX</b></td> +</tr> + +<tr> +<td WIDTH="33%">CLASS</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_VERSION</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_COLORMODEL</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">RANGE_INDEX</td> + +<td WIDTH="33%">N</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_MINMAXNUMERIC</td> + +<td WIDTH="33%">O</td> + +<td WIDTH="34%">O</td> +</tr> +</table> + +<h3> +2.3. Storage Layout for Palettes</h3> +The values of the Palette are stored as a dataset. The datatype can +be any HDF 5 atomic numeric type. The dataset will have dimensions +(<tt>nentries</tt> by <tt>ncomponents</tt>), where '<tt>nentries</tt>' +is the number of colors (usually 256) and '<tt>ncomponents'</tt> is the +number of values per color (3 for <b>RGB</b>, 4 for <b>CMYK</b>, etc.) +<br> +<h2> +<a NAME="Sect3"></a>3. Consistency and Correlation of Image and Palette +Attributes</h2> +The objects in this specification are an extension to the base HDF5 specification +and library. They are accessible with the standard HDF5 library, +but the semantics of the objects are not enforced by the base library. +For example, it is perfectly possible to add an attribute called <b>IMAGE</b> +to <i>any</i> dataset, or to include an object reference to <i>any</i> +HDF5 dataset in a <b>PALETTE</b> attribute. This would be a valid +HDF5 file, but not conformant to this specification. The rules defined +in this specification must be implemented with appropriate software, and +applications must use conforming software to assure correctness. +<p>The Image and Palette specifications include several redundant standard +attributes, such as the <b>IMAGE_COLORMODEL</b> and the <b>PAL_COLORMODEL</b>. +These attributes are informative not normative, in that it is acceptable +to attach a Palette to an Image dataset even if their attributes do not +match. Software is not required to enforce consistency, and files +may contain mismatched associations of Images and Palettes. In all +cases, it is up to applications to determine what kinds of images and color +models can be supported. +<p>For example, an Image that was created from a file with an "RGB" may +have a "YUV" Palette in its <b>PALETTE</b> attribute array. This +would be a legal HDF5 file and also conforms to this specification, although +it may or may not be correct for a given application.</p> + +</body> +</html> diff --git a/doxygen/examples/PaletteExample1.gif b/doxygen/examples/PaletteExample1.gif Binary files differnew file mode 100644 index 0000000..8694d9d --- /dev/null +++ b/doxygen/examples/PaletteExample1.gif diff --git a/doxygen/examples/Palettes.fm.anc.gif b/doxygen/examples/Palettes.fm.anc.gif Binary files differnew file mode 100644 index 0000000..d344c03 --- /dev/null +++ b/doxygen/examples/Palettes.fm.anc.gif diff --git a/doxygen/examples/TableSpec.html b/doxygen/examples/TableSpec.html new file mode 100644 index 0000000..474176e --- /dev/null +++ b/doxygen/examples/TableSpec.html @@ -0,0 +1,193 @@ +<html> +<head> + <title>HDF5 Table Specification</title> +</head> + +The HDF5 specification defines the standard objects and storage for the +standard HDF5 objects. (For information about the HDF5 library, model and +specification, see the HDF documentation.) This document is an additional +specification do define a standard profile for how to store tables in HDF5. +Table data in HDF5 is stored as HDF5 datasets with standard attributes to define +the properties of the tables. + +<h2> +1. Overview</h2> +A generic table is a sequence of records, each record has a name and a type. +Table data is stored as an HDF5 one dimensional compound dataset. A table +is defined as a collection of records whose values are stored in fixed-length +fields. All records have the same structure and all values in each field have +the same data type. +<p>The dataset for a table is distinguished from other datasets by giving +it an attribute "CLASS=TABLE". +Optional attributes allow the storage of a title for the Table and for +each column, and a fill value for each column. +<h2> +2. Table Attributes</h2> +The attributes for the Table are strings. They are written with the <a href="RM_H5LT.html#H5LTset_attribute_string"><code>H5LTset_attribute_string</code></a> +Lite API function. "Required" attributes must always be used. "Optional" attributes +must be used when required. +<br> +<h4> +Attributes</h4> + +<dl> +<dt> +Attribute name="<b>CLASS</b>" (Required)</dt> + +<dd> +This attribute is type H5T_C_S1, with size 5.</dd> + +<dd> +For all Tables, the value of this attribute is "TABLE".</dd> + +<dd> +This attribute identifies this data set as intended to be interpreted as Table that conforms to the specifications on this page.</dd> +</dl> + +<dl> +Attribute name="<b>VERSION</b>" (Required) + +<dd> +This attribute is of type H5T_C_S1, with size corresponding to the length +of the version string. This attribute identifies the version number +of this specification to which it conforms. The current version number +is "0.2".</dd> + +</dl> + +<dl> +<dt> +Attribute name="<b>TITLE</b>" (Optional)</dt> + +<dd> +The <b>TITLE</b> is an optional String that is to be used as the +informative title of the whole table. +The <b>TITLE</b> is set with the parameter <code> table_title</code> of the function +<a href="RM_H5TB.html#H5TBmake_table"> <code> H5TBmake_table</code></a>. </dd> +</dl> + +<dl> +<dt> +Attribute name="<b>FIELD_(n)_NAME</b>" (Required)</dt> + +<dd> +The <b>FIELD_(n)_NAME</b> is an optional String that is to be used as the +informative title of column <b>n</b> of the table. +For each of the fields the word FIELD_ is concatenated with + the zero based field (n) index together with the name of the field.</dd> + +</dl> +<dl> +<dt> +Attribute name="<b>FIELD_(n)_FILL</b>" (Optional)</dt> + +<dd> +The <b>FIELD_(n)_FILL</b> is an optional String that is the fill value for +column <b>n</b> of the table. +For each of the fields the word FIELD_ is concatenated with + the zero based field (n) index together with the fill value, if present. +This value is written only when a fill value is defined for the table.</dd> + +</dl> + +<dl> + +<br> +<center><table BORDER=2 BGCOLOR="#FFFFFF" > +<caption><b>Table 1. Attributes of an Image Dataset</b></caption> + +<tr> +<td><b>Attribute Name</b></td> + +<td><b>(R = Required</b> +<br><b>O= Optional)</b></td> + +<td><b>Type</b></td> + +<td><b>String Size</b></td> + +<td><b>Value</b></td> +</tr> + +<tr> +<td>CLASS</td> + +<td>R</td> + +<td>String</td> + +<td>5</td> + +<td>"TABLE"</td> +</tr> + +<tr> +<td>VERSION</td> + +<td>R</td> + +<td>String</td> + +<td>3</td> + +<td>"0.2"</td> +</tr> + +<tr> +<td>TITLE</td> + +<td>O</td> + +<td>String</td> + +<td> </td> + +<td> + +<tr> +<td>FIELD_(n)_NAME</td> + +<td>R</td> + +<td>String</td> + +<td> </td> + +<td> + + +<tr> +<td>FIELD_(n)_FILL</td> + +<td>O*</td> + +<td>String</td> + +<td> </td> + +<td> + +</table> +</center> + + </dl> +<p> +<center> + +</center> +<i>* </i>The attribute FIELD_(n)_FILL is written to the table if a fill value is +specified on the creation of the Table. Otherwise, it is not.<p>The following +section of code shows the calls necessary to the creation of a table. + +<p><code>/* Create a new HDF5 file using default properties. */<br> + file_id = H5Fcreate( "my_table.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT );</code> </p> + +<p><code>/* Call the make table function */<br> +</code> <code>H5TBmake_table( "Table Title", file_id, "Table1", NFIELDS, NRECORDS, dst_size, <br> + field_names, dst_offset, field_type, <br> + chunk_size, fill_data, compress, p_data ) </code> </p> + +<p><code> /* Close the file. */<br> + status = H5Fclose( file_id );</code> </p> + +</body> diff --git a/doxygen/examples/ThreadSafeLibrary.html b/doxygen/examples/ThreadSafeLibrary.html new file mode 100644 index 0000000..8daf386 --- /dev/null +++ b/doxygen/examples/ThreadSafeLibrary.html @@ -0,0 +1,787 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<html lang="en-US"> +<head> + <title>Thread Safe Library</title> +</head> + +<h1>1. Library header files and conditional compilation</h1> + +<p> +The following code is placed at the beginning of H5private.h: +</p> + +<blockquote> + <pre> + #ifdef H5_HAVE_THREADSAFE + #include <pthread.h> + #endif + </pre> +</blockquote> + +<p> +<code>H5_HAVE_THREADSAFE</code> is defined when the HDF-5 library is +compiled with the --enable-threadsafe configuration option. In general, +code for the non-threadsafe version of HDF-5 library are placed within +the <code>#else</code> part of the conditional compilation. The exception +to this rule are the changes to the <code>FUNC_ENTER</code> (in +H5private.h), <code>HRETURN</code> and <code>HRETURN_ERROR</code> (in +H5Eprivate.h) macros (see section 3.2). +</p> + + +<h1>2. Global variables/structures</h1> + +<h2>2.1 Global library initialization variable</h2> + +<p> +In the threadsafe implementation, the global library initialization +variable <code>H5_libinit_g</code> is changed to a global structure +consisting of the variable with its associated lock (locks are explained +in section 4.1): +</p> + +<blockquote> + <pre> + hbool_t H5_libinit_g = FALSE; + </pre> +</blockquote> + +<p> +becomes +</p> + +<blockquote> + <pre> + H5_api_t H5_g; + </pre> +</blockquote> + +<p> +where <code>H5_api_t</code> is +</p> + +<blockquote> + <pre> + typedef struct H5_api_struct { + H5_mutex_t init_lock; /* API entrance mutex */ + hbool_t H5_libinit_g; + } H5_api_t; + </pre> +</blockquote> + +<p> +All former references to <code>H5_libinit_g</code> in the library are now +made using the macro <code>H5_INIT_GLOBAL</code>. If the threadsafe +library is to be used, the macro is set to <code>H5_g.H5_libinit_g</code> +instead. +</p> + +<h2>2.2 Global serialization variable</h2> + +<p> +A new global boolean variable <code>H5_allow_concurrent_g</code> is used +to determine if multiple threads are allowed to an API call +simultaneously. This is set to <code>FALSE</code>. +</p> + +<p> +All APIs that are allowed to do so have their own local variable that +shadows the global variable and is set to <code>TRUE</code>. In phase 1, +no such APIs exist. +</p> + +<p> +It is defined in <code>H5.c</code> as follows: +</p> + +<blockquote> + <pre> + hbool_t H5_allow_concurrent_g = FALSE; + </pre> +</blockquote> + +<h2>2.3 Global thread initialization variable</h2> + +<p> +The global variable <code>H5_first_init_g</code> of type +<code>pthread_once_t</code> is used to allow only the first thread in the +application process to call an initialization function using +<code>pthread_once</code>. All subsequent calls to +<code>pthread_once</code> by any thread are disregarded. +</p> + +<p> +The call sets up the mutex in the global structure <code>H5_g</code> (see +section 3.1) via an initialization function +<code>H5_first_thread_init</code>. The first thread initialization +function is described in section 4.2. +</p> + +<p> +<code>H5_first_init_g</code> is defined in <code>H5.c</code> as follows: +</p> + +<blockquote> + <pre> + pthread_once_t H5_first_init_g = PTHREAD_ONCE_INIT; + </pre> +</blockquote> + +<h2>2.4 Global key for per-thread error stacks</h2> + +<p> +A global pthread-managed key <code>H5_errstk_key_g</code> is used to +allow pthreads to maintain a separate error stack (of type +<code>H5E_t</code>) for each thread. This is defined in <code>H5.c</code> +as: +</p> + +<blockquote> + <pre> + pthread_key_t H5_errstk_key_g; + </pre> +</blockquote> + +<p> +Error stack management is described in section 4.3. +</p> + +<h2>2.5 Global structure and key for thread cancellation prevention</h2> + +<p> +We need to preserve the thread cancellation status of each thread +individually by using a key <code>H5_cancel_key_g</code>. The status is +preserved using a structure (of type <code>H5_cancel_t</code>) which +maintains the cancellability state of the thread before it entered the +library and a count (which works very much like the recursive lock +counter) which keeps track of the number of API calls the thread makes +within the library. +</p> + +<p> +The structure is defined in <code>H5private.h</code> as: +</p> + +<blockquote> + <pre> + /* cancelability structure */ + typedef struct H5_cancel_struct { + int previous_state; + unsigned int cancel_count; + } H5_cancel_t; + </pre> +</blockquote> + +<p> +Thread cancellation is described in section 4.4. +</p> + + +<h1>3. Changes to Macro expansions</h1> + +<h2>3.1 Changes to FUNC_ENTER</h2> + +<p> +The <code>FUNC_ENTER</code> macro is now extended to include macro calls +to initialize first threads, disable cancellability and wraps a lock +operation around the checking of the global initialization flag. It +should be noted that the cancellability should be disabled before +acquiring the lock on the library. Doing so otherwise would allow the +possibility that the thread be cancelled just after it has acquired the +lock on the library and in that scenario, if the cleanup routines are not +properly set, the library would be permanently locked out. +</p> + +<p> +The additional macro code and new macro definitions can be found in +Appendix E.1 to E.5. The changes are made in <code>H5private.h</code>. +</p> + +<h2>3.2 Changes to HRETURN and HRETURN_ERROR</h2> + +<p> +The <code>HRETURN</code> and <code>HRETURN_ERROR</code> macros are the +counterparts to the <code>FUNC_ENTER</code> macro described in section +3.1. <code>FUNC_LEAVE</code> makes a macro call to <code>HRETURN</code>, +so it is also covered here. +</p> + +<p> +The basic changes to these two macros involve adding macro calls to call +an unlock operation and re-enable cancellability if necessary. It should +be noted that the cancellability should be re-enabled only after the +thread has released the lock to the library. The consequence of doing +otherwise would be similar to that described in section 3.1. +</p> + +<p> +The additional macro code and new macro definitions can be found in +Appendix E.9 to E.9. The changes are made in <code>H5Eprivate.h</code>. +</p> + +<h1>4. Implementation of threadsafe functionality</h1> + +<h2>4.1 Recursive Locks</h2> + +<p> +A recursive mutex lock m allows a thread t1 to successfully lock m more +than once without blocking t1. Another thread t2 will block if t2 tries +to lock m while t1 holds the lock to m. If t1 makes k lock calls on m, +then it also needs to make k unlock calls on m before it releases the +lock. +</p> + +<p> +Our implementation of recursive locks is built on top of a pthread mutex +lock (which is not recursive). It makes use of a pthread condition +variable to have unsuccessful threads wait on the mutex. Waiting threads +are awaken by a signal from the final unlock call made by the thread +holding the lock. +</p> + +<p> +Recursive locks are defined to be the following type +(<code>H5private.h</code>): +</p> + +<blockquote> + <pre> + typedef struct H5_mutex_struct { + pthread_t owner_thread; /* current lock owner */ + pthread_mutex_t atomic_lock; /* lock for atomicity of new mechanism */ + pthread_cond_t cond_var; /* condition variable */ + unsigned int lock_count; + } H5_mutex_t; + </pre> +</blockquote> + +<p> +Detailed implementation code can be found in Appendix A. The +implementation changes are made in <code>H5TS.c</code>. +</p> + +<h2>4.2 First thread initialization</h2> + +<p> +Because the mutex lock associated with a recursive lock cannot be +statically initialized, a mechanism is required to initialize the +recursive lock associated with <code>H5_g</code> so that it can be used +for the first time. +</p> + +<p> +The pthreads library allows this through the pthread_once call which as +described in section 3.3 allows only the first thread accessing the +library in an application to initialize <code>H5_g</code>. +</p> + +<p> +In addition to initializing <code>H5_g</code>, it also initializes the +key (see section 3.4) for use with per-thread error stacks (see section +4.3). +</p> + +<p> +The first thread initialization mechanism is implemented as the function +call <code>H5_first_thread_init()</code> in <code>H5TS.c</code>. This is +described in appendix B. +</p> + +<h2>4.3 Per-thread error stack management</h2> + +<p> +Pthreads allows individual threads to access dynamic and persistent +per-thread data through the use of keys. Each key is associated with +a table that maps threads to data items. Keys can be initialized by +<code>pthread_key_create()</code> in pthreads (see sections 3.4 and 4.2). +Per-thread data items are accessed using a key through the +<code>pthread_getspecific()</code> and <code>pthread_setspecific()</code> +calls to read and write to the association table respectively. +</p> + +<p> +Per-thread error stacks are accessed through the key +<code>H5_errstk_key_g</code> which is initialized by the first thread +initialization call (see section 4.2). +</p> + +<p> +In the non-threadsafe version of the library, there is a global stack +variable <code>H5E_stack_g[1]</code> which is no longer defined in the +threadsafe version. At the same time, the macro call to gain access to +the error stack <code>H5E_get_my_stack</code> is changed from: +</p> + +<blockquote> + <pre> + #define H5E_get_my_stack() (H5E_stack_g+0) + </pre> +</blockquote> + +<p> +to: +</p> + +<blockquote> + <pre> + #define H5E_get_my_stack() H5E_get_stack() + </pre> +</blockquote> + +<p> +where <code>H5E_get_stack()</code> is a surrogate function that does the +following operations: +</p> + +<ol> + <li>if a thread is attempting to get an error stack for the first + time, the error stack is dynamically allocated for the thread and + associated with <code>H5_errstk_key_g</code> using + <code>pthread_setspecific()</code>. The way we detect if it is the + first time is through <code>pthread_getspecific()</code> which + returns <code>NULL</code> if no previous value is associated with + the thread using the key.</li> + + <li>if <code>pthread_getspecific()</code> returns a non-null value, + then that is the pointer to the error stack associated with the + thread and the stack can be used as usual.</li> +</ol> + +<p> +A final change to the error reporting routines is as follows; the current +implementation reports errors to always be detected at thread 0. In the +threadsafe implementation, this is changed to report the number returned +by a call to <code>pthread_self()</code>. +</p> + +<p> +The change in code (reflected in <code>H5Eprint</code> of file +<code>H5E.c</code>) is as follows: +</p> + +<blockquote> + <pre> + #ifdef H5_HAVE_THREADSAFE + fprintf (stream, "HDF5-DIAG: Error detected in thread %d." + ,pthread_self()); + #else + fprintf (stream, "HDF5-DIAG: Error detected in thread 0."); + #endif + </pre> +</blockquote> + +<p> +Code for <code>H5E_get_stack()</code> can be found in Appendix C. All the +above changes were made in <code>H5E.c</code>. +</p> + +<h2>4.4 Thread Cancellation safety</h2> + +<p> +To prevent thread cancellations from killing a thread while it is in the +library, we maintain per-thread information about the cancellability +status of the thread before it entered the library so that we can restore +that same status when the thread leaves the library. +</p> + +<p> +By <i>enter</i> and <i>leave</i> the library, we mean the points when a +thread makes an API call from a user application and the time that API +call returns. Other API or callback function calls made from within that +API call are considered <i>within</i> the library. +</p> + +<p> +Because other API calls may be made from within the first API call, we +need to maintain a counter to determine which was the first and +correspondingly the last return. +</p> + +<p> +When a thread makes an API call, the macro <code>H5_API_SET_CANCEL</code> +calls the worker function <code>H5_cancel_count_inc()</code> which does +the following: +</p> + +<ol> + <li>if this is the first time the thread has entered the library, + a new cancellability structure needs to be assigned to it.</li> + <li>if the thread is already within the library when the API call is + made, then cancel_count is simply incremented. Otherwise, we set + the cancellability state to <code>PTHREAD_CANCEL_DISABLE</code> + while storing the previous state into the cancellability structure. + <code>cancel_count</code> is also incremented in this case.</li> +</ol> + +<p> +When a thread leaves an API call, the macro +<code>H5_API_UNSET_CANCEL</code> calls the worker function +<code>H5_cancel_count_dec()</code> which does the following: +</p> + +<ol> + <li>if <code>cancel_count</code> is greater than 1, indicating that the + thread is not yet about to leave the library, then + <code>cancel_count</code> is simply decremented.</li> + <li>otherwise, we reset the cancellability state back to its original + state before it entered the library and decrement the count (back + to zero).</li> +</ol> + +<p> +<code>H5_cancel_count_inc</code> and <code>H5_cancel_count_dec</code> are +described in Appendix D and may be found in <code>H5TS.c</code>. +</p> + +<h1>5. Test programs</h1> + +<p> +Except where stated, all tests involve 16 simultaneous threads that make +use of HDF-5 API calls without any explicit synchronization typically +required in a non-threadsafe environment. +</p> + +<h2>5.1 Data set create and write</h2> + +<p> +The test program sets up 16 threads to simultaneously create 16 +different datasets named from <i>zero</i> to <i>fifteen</i> for a single +file and then writing an integer value into that dataset equal to the +dataset's named value. +</p> + +<p> +The main thread would join with all 16 threads and attempt to match the +resulting HDF-5 file with expected results - that each dataset contains +the correct value (0 for <i>zero</i>, 1 for <i>one</i> etc ...) and all +datasets were correctly created. +</p> + +<p> +The test is implemented in the file <code>ttsafe_dcreate.c</code>. +</p> + +<h2>5.2 Test on error stack</h2> + +<p> +The error stack test is one in which 16 threads simultaneously try to +create datasets with the same name. The result, when properly serialized, +should be equivalent to 16 attempts to create the dataset with the same +name. +</p> + +<p> +The error stack implementation runs correctly if it reports 15 instances +of the dataset name conflict error and finally generates a correct HDF-5 +containing that single dataset. Each thread should report its own stack +of errors with a thread number associated with it. +</p> + +<p> +The test is implemented in the file <code>ttsafe_error.c</code>. +</p> + +<h2>5.3 Test on cancellation safety</h2> + +<p> +The main idea in thread cancellation safety is as follows; a child thread +is spawned to create and write to a dataset. Following that, it makes a +<code>H5Diterate</code> call on that dataset which activates a callback +function. +</p> + +<p> +A deliberate barrier is invoked at the callback function which waits for +both the main and child thread to arrive at that point. After that +happens, the main thread proceeds to make a thread cancel call on the +child thread while the latter sleeps for 3 seconds before proceeding to +write a new value to the dataset. +</p> + +<p> +After the iterate call, the child thread logically proceeds to wait +another 3 seconds before writing another newer value to the dataset. +</p> + +<p> +The test is correct if the main thread manages to read the second value +at the end of the test. This means that cancellation did not take place +until the end of the iteration call despite of the 3 second wait within +the iteration callback and the extra dataset write operation. +Furthermore, the cancellation should occur before the child can proceed +to write the last value into the dataset. +</p> + +<h2>5.4 Test on attribute creation</h2> + +<p> +A main thread makes 16 threaded calls to <code>H5Acreate</code> with a +generated name for each attribute. Sixteen attributes should be created +for the single dataset in random (chronological) order and receive values +depending on its generated attribute name (e.g. <i>attrib010</i> would +receive the value 10). +</p> + +<p> +After joining with all child threads, the main thread proceeds to read +each attribute by generated name to see if the value tallies. Failure is +detected if the attribute name does not exist (meaning they were never +created) or if the wrong values were read back. +</p> + +<h1>A. Recursive Lock implementation code</h1> + +<blockquote> + <pre> + void H5_mutex_init(H5_mutex_t *H5_mutex) + { + H5_mutex->owner_thread = NULL; + pthread_mutex_init(&H5_mutex->atomic_lock, NULL); + pthread_cond_init(&H5_mutex->cond_var, NULL); + H5_mutex->lock_count = 0; + } + + void H5_mutex_lock(H5_mutex_t *H5_mutex) + { + pthread_mutex_lock(&H5_mutex->atomic_lock); + + if (pthread_equal(pthread_self(), H5_mutex->owner_thread)) { + /* already owned by self - increment count */ + H5_mutex->lock_count++; + } else { + if (H5_mutex->owner_thread == NULL) { + /* no one else has locked it - set owner and grab lock */ + H5_mutex->owner_thread = pthread_self(); + H5_mutex->lock_count = 1; + } else { + /* if already locked by someone else */ + while (1) { + pthread_cond_wait(&H5_mutex->cond_var, &H5_mutex->atomic_lock); + + if (H5_mutex->owner_thread == NULL) { + H5_mutex->owner_thread = pthread_self(); + H5_mutex->lock_count = 1; + break; + } /* else do nothing and loop back to wait on condition*/ + } + } + } + + pthread_mutex_unlock(&H5_mutex->atomic_lock); + } + + void H5_mutex_unlock(H5_mutex_t *H5_mutex) + { + pthread_mutex_lock(&H5_mutex->atomic_lock); + H5_mutex->lock_count--; + + if (H5_mutex->lock_count == 0) { + H5_mutex->owner_thread = NULL; + pthread_cond_signal(&H5_mutex->cond_var); + } + pthread_mutex_unlock(&H5_mutex->atomic_lock); + } + </pre> +</blockquote> + +<h1>B. First thread initialization</h1> + +<blockquote> + <pre> + void H5_first_thread_init(void) + { + /* initialize global API mutex lock */ + H5_g.H5_libinit_g = FALSE; + H5_g.init_lock.owner_thread = NULL; + pthread_mutex_init(&H5_g.init_lock.atomic_lock, NULL); + pthread_cond_init(&H5_g.init_lock.cond_var, NULL); + H5_g.init_lock.lock_count = 0; + + /* initialize key for thread-specific error stacks */ + pthread_key_create(&H5_errstk_key_g, NULL); + + /* initialize key for thread cancellability mechanism */ + pthread_key_create(&H5_cancel_key_g, NULL); + } + </pre> +</blockquote> + + +<h1>C. Per-thread error stack acquisition</h1> + +<blockquote> + <pre> + H5E_t *H5E_get_stack(void) + { + H5E_t *estack; + + if (estack = pthread_getspecific(H5_errstk_key_g)) { + return estack; + } else { + /* no associated value with current thread - create one */ + estack = (H5E_t *)malloc(sizeof(H5E_t)); + pthread_setspecific(H5_errstk_key_g, (void *)estack); + return estack; + } + } + </pre> +</blockquote> + +<h1>D. Thread cancellation mechanisms</h1> + +<blockquote> + <pre> + void H5_cancel_count_inc(void) + { + H5_cancel_t *cancel_counter; + + if (cancel_counter = pthread_getspecific(H5_cancel_key_g)) { + /* do nothing here */ + } else { + /* + * first time thread calls library - create new counter and + * associate with key + */ + cancel_counter = (H5_cancel_t *)malloc(sizeof(H5_cancel_t)); + cancel_counter->cancel_count = 0; + pthread_setspecific(H5_cancel_key_g, (void *)cancel_counter); + } + + if (cancel_counter->cancel_count == 0) { + /* thread entering library */ + pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, + &(cancel_counter->previous_state)); + } + + cancel_counter->cancel_count++; + } + + void H5_cancel_count_dec(void) + { + H5_cancel_t *cancel_counter = pthread_getspecific(H5_cancel_key_g); + + if (cancel_counter->cancel_count == 1) + pthread_setcancelstate(cancel_counter->previous_state, NULL); + + cancel_counter->cancel_count--; + } + </pre> +</blockquote> + +<h1>E. Macro expansion codes</h1> + +<h2>E.1 <code>FUNC_ENTER</code></h2> + +<blockquote> + <pre> + /* Initialize the library */ \ + H5_FIRST_THREAD_INIT \ + H5_API_UNSET_CANCEL \ + H5_API_LOCK_BEGIN \ + if (!(H5_INIT_GLOBAL)) { \ + H5_INIT_GLOBAL = TRUE; \ + if (H5_init_library() < 0) { \ + HRETURN_ERROR (H5E_FUNC, H5E_CANTINIT, err, \ + "library initialization failed"); \ + } \ + } \ + H5_API_LOCK_END \ + : + : + : + </pre> +</blockquote> + +<h2>E.2 <code>H5_FIRST_THREAD_INIT</code></h2> + +<blockquote> + <pre> + /* Macro for first thread initialization */ + #define H5_FIRST_THREAD_INIT \ + pthread_once(&H5_first_init_g, H5_first_thread_init); + </pre> +</blockquote> + + +<h2>E.3 <code>H5_API_UNSET_CANCEL</code></h2> + +<blockquote> + <pre> + #define H5_API_UNSET_CANCEL \ + if (H5_IS_API(FUNC)) { \ + H5_cancel_count_inc(); \ + } + </pre> +</blockquote> + + +<h2>E.4 <code>H5_API_LOCK_BEGIN</code></h2> + +<blockquote> + <pre> + #define H5_API_LOCK_BEGIN \ + if (H5_IS_API(FUNC)) { \ + H5_mutex_lock(&H5_g.init_lock); + </pre> +</blockquote> + + +<h2>E.5 <code>H5_API_LOCK_END</code></h2> + +<blockquote> + <pre> + #define H5_API_LOCK_END } + </pre> +</blockquote> + + +<h2>E.6 <code>HRETURN</code> and <code>HRETURN_ERROR</code></h2> + +<blockquote> + <pre> + : + : + H5_API_UNLOCK_BEGIN \ + H5_API_UNLOCK_END \ + H5_API_SET_CANCEL \ + return ret_val; \ + } + </pre> +</blockquote> + +<h2>E.7 <code>H5_API_UNLOCK_BEGIN</code></h2> + +<blockquote> + <pre> + #define H5_API_UNLOCK_BEGIN \ + if (H5_IS_API(FUNC)) { \ + H5_mutex_unlock(&H5_g.init_lock); + </pre> +</blockquote> + +<h2>E.8 <code>H5_API_UNLOCK_END</code></h2> + +<blockquote> + <pre> + #define H5_API_UNLOCK_END } + </pre> +</blockquote> + + +<h2>E.9 <code>H5_API_SET_CANCEL</code></h2> + +<blockquote> + <pre> + #define H5_API_SET_CANCEL \ + if (H5_IS_API(FUNC)) { \ + H5_cancel_count_dec(); \ + } + </pre> +</blockquote> + +<h2>By Chee Wai Lee</h2> +<h4>By Bill Wendling</h4> + +</body> +</html> diff --git a/doxygen/examples/VFL.html b/doxygen/examples/VFL.html new file mode 100644 index 0000000..9776f96 --- /dev/null +++ b/doxygen/examples/VFL.html @@ -0,0 +1,1601 @@ +<HTML> +<HEAD> +<!-- This HTML file has been created by texi2html 1.51 + from VFL.texi on 18 November 1999 --> + +<TITLE>HDF5 Virtual File Layer</TITLE> +</HEAD> + + +<!-- + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * Copyright by the Board of Trustees of the University of Illinois. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the files COPYING and Copyright.html. COPYING can be found at the root * + * of the source code distribution tree; Copyright.html can be found at the * + * root level of an installed copy of the electronic HDF5 document set and * + * is linked from the top-level documents page. It can also be found at * + * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * + * access to either file, you may request a copy from help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + --> + + +<BODY> + +<strong>Revision History</strong> +<p>Initial document, 18 November 1999.</p> + +<p>Updated on 10/24/00, Quincey Koziol</p> + +<p>Added the section “Programming Note for C++ Developers Using C +Functions,” 08/23/2012, Mark Evans + + + +<P> +<P><HR><P> +<H1>Table of Contents</H1> +<UL> +<LI><A NAME="TOC1" HREF="#SEC1">Introduction</A> +<LI><A NAME="TOC2" HREF="#SEC2">Using a File Driver</A> +<UL> +<LI><A NAME="TOC3" HREF="#SEC3">Driver Header Files</A> +<LI><A NAME="TOC4" HREF="#SEC4">Creating and Opening Files</A> +<LI><A NAME="TOC5" HREF="#SEC5">Performing I/O</A> +<LI><A NAME="TOC6" HREF="#SEC6">File Driver Interchangeability</A> +</UL> +<LI><A NAME="TOC7" HREF="#SEC7">Implementation of a Driver</A> +<UL> +<LI><A NAME="TOC8" HREF="#SEC8">Mode Functions</A> +<LI><A NAME="TOC9" HREF="#SEC9">File Functions</A> +<UL> +<LI><A NAME="TOC10" HREF="#SEC10">Opening Files</A> +<LI><A NAME="TOC11" HREF="#SEC11">Closing Files</A> +<LI><A NAME="TOC12" HREF="#SEC12">File Keys</A> +<LI><A NAME="TOC13" HREF="#SEC13">Saving Modes Across Opens</A> +</UL> +<LI><A NAME="TOC14" HREF="#SEC14">Address Space Functions</A> +<UL> +<LI><A NAME="TOC15" HREF="#SEC15">Userblock and Superblock</A> +<LI><A NAME="TOC16" HREF="#SEC16">Allocation of Format Regions</A> +<LI><A NAME="TOC17" HREF="#SEC17">Freeing Format Regions</A> +<LI><A NAME="TOC18" HREF="#SEC18">Querying Address Range</A> +</UL> +<LI><A NAME="TOC19" HREF="#SEC19">Data Functions</A> +<UL> +<LI><A NAME="TOC20" HREF="#SEC20">Contiguous I/O Functions</A> +<LI><A NAME="TOC21" HREF="#SEC21">Flushing Cached Data</A> +</UL> +<LI><A NAME="TOC22" HREF="#SEC22">Optimization Functions</A> +<LI><A NAME="TOC23" HREF="#SEC23">Registration of a Driver</A> + <ul> + <li><a name="TOCProgNote" href="#SECProgNote"> + Programming Note for C++ Developers Using C Functions</a> + </li> + </ul> +<LI><A NAME="TOC24" HREF="#SEC24">Querying Driver Information</A> +</UL> +<LI><A NAME="TOC25" HREF="#SEC25">Miscellaneous</A> +</UL> +<P><HR><P> + + +<H1><A NAME="SEC1" HREF="#TOC1">Introduction</A></H1> + +<P> +The HDF5 file format describes how HDF5 data structures and dataset raw +data are mapped to a linear <STRONG>format address space</STRONG> and the HDF5 +library implements that bidirectional mapping in terms of an +API. However, the HDF5 format specifications do <EM>not</EM> indicate how +the format address space is mapped onto storage and HDF (version 5 and +earlier) simply mapped the format address space directly onto a single +file by convention. + +</P> +<P> +Since early versions of HDF5 it became apparent that users want the ability to +map the format address space onto different types of storage (a single file, +multiple files, local memory, global memory, network distributed global +memory, a network protocol, <I>etc</I>.) with various types of maps. For +instance, some users want to be able to handle very large format address +spaces on operating systems that support only 2GB files by partitioning the +format address space into equal-sized parts each served by a separate +file. Other users want the same multi-file storage capability but want to +partition the address space according to purpose (raw data in one file, object +headers in another, global heap in a third, <I>etc.</I>) in order to improve I/O +speeds. + +</P> +<P> +In fact, the number of storage variations is probably larger than the +number of methods that the HDF5 team is capable of implementing and +supporting. Therefore, a <STRONG>Virtual File Layer</STRONG> API is being +implemented which will allow application teams or departments to design +and implement their own mapping between the HDF5 format address space +and storage, with each mapping being a separate <STRONG>file driver</STRONG> +(possibly written in terms of other file drivers). The HDF5 team will +provide a small set of useful file drivers which will also serve as +examples for those who which to write their own: + +</P> +<DL COMPACT> + +<DT><CODE>H5FD_SEC2</CODE> +<DD> +This is the default driver which uses Posix file-system functions like +<CODE>read</CODE> and <CODE>write</CODE> to perform I/O to a single file. All I/O +requests are unbuffered although the driver does optimize file seeking +operations to some extent. + +<DT><CODE>H5FD_STDIO</CODE> +<DD> +This driver uses functions from <TT>`stdio.h'</TT> to perform buffered I/O +to a single file. + +<DT><CODE>H5FD_CORE</CODE> +<DD> +This driver performs I/O directly to memory and can be used to create small +temporary files that never exist on permanent storage. This type of storage is +generally very fast since the I/O consists only of memory-to-memory copy +operations. + +<DT><CODE>H5FD_MPIIO</CODE> +<DD> +This is the driver of choice for accessing files in parallel using MPI and +MPI-IO. It is only predefined if the library is compiled with parallel I/O +support. + +<DT><CODE>H5FD_FAMILY</CODE> +<DD> +Large format address spaces are partitioned into more manageable pieces and +sent to separate storage locations using an underlying driver of the user's +choice. The <CODE>h5repart</CODE> tool can be used to change the sizes of the +family members when stored as files or to convert a family of files to a +single file or vice versa. + +<DT><CODE>H5FD_SPLIT</CODE> +<DD> +The format address space is split into meta data and raw data and each is +mapped onto separate storage using underlying drivers of the user's +choice. The meta data storage can be read by itself (for limited +functionality) or both files can be accessed together. +</DL> + + + +<H1><A NAME="SEC2" HREF="#TOC2">Using a File Driver</A></H1> + +<P> +Most application writers will use a driver defined by the HDF5 library or +contributed by another programming team. This chapter describes how existing +drivers are used. + +</P> + + + +<H2><A NAME="SEC3" HREF="#TOC3">Driver Header Files</A></H2> + +<P> +Each file driver is defined in its own public header file which should +be included by any application which plans to use that driver. The +predefined drivers are in header files whose names begin with +<SAMP>`H5FD'</SAMP> followed by the driver name and <SAMP>`.h'</SAMP>. The <TT>`hdf5.h'</TT> +header file includes all the predefined driver header files. + +</P> +<P> +Once the appropriate header file is included a symbol of the form +<SAMP>`H5FD_'</SAMP> followed by the upper-case driver name will be the driver +identification number.<A NAME="DOCF1" HREF="#FOOT1">(1)</A> However, the +value may change if the library is closed (<I>e.g.</I>, by calling +<CODE>H5close</CODE>) and the symbol is referenced again. + +</P> + + +<H2><A NAME="SEC4" HREF="#TOC4">Creating and Opening Files</A></H2> + +<P> +In order to create or open a file one must define the method by which the +storage is accessed<A NAME="DOCF2" HREF="#FOOT2">(2)</A> and does so by creating a file access property list<A NAME="DOCF3" HREF="#FOOT3">(3)</A> which is passed to the <CODE>H5Fcreate</CODE> or +<CODE>H5Fopen</CODE> function. A default file access property list is created by +calling <CODE>H5Pcreate</CODE> and then the file driver information is inserted by +calling a driver initialization function such as <CODE>H5Pset_fapl_family</CODE>: + +</P> + +<PRE> +hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); +size_t member_size = 100*1024*1024; /*100MB*/ +H5Pset_fapl_family(fapl, member_size, H5P_DEFAULT); +hid_t file = H5Fcreate("foo%05d.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl); +H5Pclose(fapl); +</PRE> + +<P> +Each file driver will have its own initialization function +whose name is <CODE>H5Pset_fapl_</CODE> followed by the driver name and which +takes a file access property list as the first argument followed by +additional driver-dependent arguments. + +</P> +<P> +An alternative to using the driver initialization function is to set the +driver directly using the <CODE>H5Pset_driver</CODE> function.<A NAME="DOCF4" HREF="#FOOT4">(4)</A> Its second argument is the file driver identifier, which may +have a different numeric value from run to run depending on the order in which +the file drivers are registered with the library. The third argument +encapsulates the additional arguments of the driver initialization +function. This method only works if the file driver writer has made the +driver-specific property list structure a public datatype, which is +often not the case. + +</P> + +<PRE> +hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); +static H5FD_family_fapl_t fa = {100*1024*1024, H5P_DEFAULT}; +H5Pset_driver(fapl, H5FD_FAMILY, &fa); +hid_t file = H5Fcreate("foo.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl); +H5Pclose(fapl); +</PRE> + +<P> +It is also possible to query the file driver information from a file access +property list by calling <CODE>H5Pget_driver</CODE> to determine the driver and then +calling a driver-defined query function to obtain the driver information: + +</P> + +<PRE> +hid_t driver = H5Pget_driver(fapl); +if (H5FD_SEC2==driver) { + /*nothing further to get*/ +} else if (H5FD_FAMILY==driver) { + hid_t member_fapl; + haddr_t member_size; + H5Pget_fapl_family(fapl, &member_size, &member_fapl); +} else if (....) { + .... +} +</PRE> + + + +<H2><A NAME="SEC5" HREF="#TOC5">Performing I/O</A></H2> + +<P> +The <CODE>H5Dread</CODE> and <CODE>H5Dwrite</CODE> functions transfer data between +application memory and the file. They both take an optional data transfer +property list which has some general driver-independent properties and +optional driver-defined properties. An application will typically perform I/O +in one of three styles via the <CODE>H5Dread</CODE> or <CODE>H5Dwrite</CODE> function: + +</P> +<P> +Like file access properties in the previous section, data transfer properties +can be set using a driver initialization function or a general purpose +function. For example, to set the MPI-IO driver to use independent access for +I/O operations one would say: + +</P> + +<PRE> +hid_t dxpl = H5Pcreate(H5P_DATA_XFER); +H5Pset_dxpl_mpio(dxpl, H5FD_MPIO_INDEPENDENT); +H5Dread(dataset, type, mspace, fspace, buffer, dxpl); +H5Pclose(dxpl); +</PRE> + +<P> +The alternative is to initialize a driver defined C <CODE>struct</CODE> and pass it +to the <CODE>H5Pset_driver</CODE> function: + +</P> + +<PRE> +hid_t dxpl = H5Pcreate(H5P_DATA_XFER); +static H5FD_mpio_dxpl_t dx = {H5FD_MPIO_INDEPENDENT}; +H5Pset_driver(dxpl, H5FD_MPIO, &dx); +H5Dread(dataset, type, mspace, fspace, buffer, dxpl); +</PRE> + +<P> +The transfer propery list can be queried in a manner similar to the file +access property list: the driver provides a function (or functions) to return +various information about the transfer property list: + +</P> + +<PRE> +hid_t driver = H5Pget_driver(dxpl); +if (H5FD_MPIO==driver) { + H5FD_mpio_xfer_t xfer_mode; + H5Pget_dxpl_mpio(dxpl, &xfer_mode); +} else { + .... +} +</PRE> + + + +<H2><A NAME="SEC6" HREF="#TOC6">File Driver Interchangeability</A></H2> + +<P> +The HDF5 specifications describe two things: the mapping of data onto a linear +<STRONG>format address space</STRONG> and the C API which performs the mapping. +However, the mapping of the format address space onto storage intentionally +falls outside the scope of the HDF5 specs. This is a direct result of the fact +that it is not generally possible to store information about how to access +storage inside the storage itself. For instance, given only the file name +<TT>`/arborea/1225/work/f%03d'</TT> the HDF5 library is unable to tell whether the +name refers to a file on the local file system, a family of files on the local +file system, a file on host <SAMP>`arborea'</SAMP> port 1225, a family of files on a +remote system, <I>etc</I>. + +</P> +<P> +Two ways which library could figure out where the storage is located are: +storage access information can be provided by the user, or the library can try +all known file access methods. This implementation uses the former method. + +</P> +<P> +In general, if a file was created with one driver then it isn't possible to +open it with another driver. There are of course exceptions: a file created +with MPIO could probably be opened with the sec2 driver, any file created +by the sec2 driver could be opened as a family of files with one member, +<I>etc</I>. In fact, sometimes a file must not only be opened with the same +driver but also with the same driver properties. The predefined drivers are +written in such a way that specifying the correct driver is sufficient for +opening a file. + +</P> + + +<H1><A NAME="SEC7" HREF="#TOC7">Implementation of a Driver</A></H1> + +<P> +A driver is simply a collection of functions and data structures which are +registered with the HDF5 library at runtime. The functions fall into these +categories: + +</P> + +<UL> +<LI>Functions which operate on modes + +<LI>Functions which operate on files + +<LI>Functions which operate on the address space + +<LI>Functions which operate on data + +<LI>Functions for driver initialization + +<LI>Optimization functions + +</UL> + + + +<H2><A NAME="SEC8" HREF="#TOC8">Mode Functions</A></H2> + +<P> +Some drivers need information about file access and data transfers which are +very specific to the driver. The information is usually implemented as a pair +of pointers to C structs which are allocated and initialized as part of an +HDF5 property list and passed down to various driver functions. There are two +classes of settings: file access modes that describe how to access the file +through the driver, and data transfer modes which are settings that control +I/O operations. Each file opened by a particular driver may have a different +access mode; each dataset I/O request for a particular file may have a +different data transfer mode. + +</P> +<P> +Since each driver has its own particular requirements for various settings, +each driver is responsible for defining the mode structures that it +needs. Higher layers of the library treat the structures as opaque but must be +able to copy and free them. Thus, the driver provides either the size of the +structure or a pair of function pointers for each of the mode types. + +</P> +<P> +<STRONG>Example:</STRONG> The family driver needs to know how the format address +space is partitioned and the file access property list to use for the +family members. + +</P> + +<PRE> +/* Driver-specific file access properties */ +typedef struct H5FD_family_fapl_t { + hsize_t memb_size; /*size of each member */ + hid_t memb_fapl_id; /*file access property list of each memb*/ +} H5FD_family_fapl_t; + +/* Driver specific data transfer properties */ +typedef struct H5FD_family_dxpl_t { + hid_t memb_dxpl_id; /*data xfer property list of each memb */ +} H5FD_family_dxpl_t; +</PRE> + +<P> +In order to copy or free one of these structures the member file access +or data transfer properties must also be copied or freed. This is done +by providing a copy and close function for each structure: + +</P> +<P> +<STRONG>Example:</STRONG> The file access property list copy and close functions +for the family driver: + +</P> + +<PRE> +static void * +H5FD_family_fapl_copy(const void *_old_fa) +{ + const H5FD_family_fapl_t *old_fa = (const H5FD_family_fapl_t*)_old_fa; + H5FD_family_fapl_t *new_fa = malloc(sizeof(H5FD_family_fapl_t)); + assert(new_fa); + + memcpy(new_fa, old_fa, sizeof(H5FD_family_fapl_t)); + new_fa->memb_fapl_id = H5Pcopy(old_fa->memb_fapl_id); + return new_fa; +} + +static herr_t +H5FD_family_fapl_free(void *_fa) +{ + H5FD_family_fapl_t *fa = (H5FD_family_fapl_t*)_fa; + H5Pclose(fa->memb_fapl_id); + free(fa); + return 0; +} +</PRE> + +<P> +Generally when a file is created or opened the file access properties +for the driver are copied into the file pointer which is returned and +they may be modified from their original value (for instance, the file +family driver modifies the member size property when opening an existing +family). In order to support the <CODE>H5Fget_access_plist</CODE> function the +driver must provide a <CODE>fapl_get</CODE> callback which creates a copy of +the driver-specific properties based on a particular file. + +</P> +<P> +<STRONG>Example:</STRONG> The file family driver copies the member size file +access property list into the return value: + +</P> + +<PRE> +static void * +H5FD_family_fapl_get(H5FD_t *_file) +{ + H5FD_family_t *file = (H5FD_family_t*)_file; + H5FD_family_fapl_t *fa = calloc(1, sizeof(H5FD_family_fapl_t*)); + + fa->memb_size = file->memb_size; + fa->memb_fapl_id = H5Pcopy(file->memb_fapl_id); + return fa; +} +</PRE> + + + +<H2><A NAME="SEC9" HREF="#TOC9">File Functions</A></H2> + +<P> +The higher layers of the library expect files to have a name and allow the +file to be accessed in various modes. The driver must be able to create a new +file, replace an existing file, or open an existing file. Opening or creating +a file should return a handle, a pointer to a specialization of the +<CODE>H5FD_t</CODE> struct, which allows read-only or read-write access and which +will be passed to the other driver functions as they are +called.<A NAME="DOCF5" HREF="#FOOT5">(5)</A> + +</P> + +<PRE> +typedef struct { + /* Public fields */ + H5FD_class_t *cls; /*class data defined below*/ + + /* Private fields -- driver-defined */ + +} H5FD_t; +</PRE> + +<P> +<STRONG>Example:</STRONG> The family driver requires handles to the underlying +storage, the size of the members for this particular file (which might be +different than the member size specified in the file access property list if +an existing file family is being opened), the name used to open the file in +case additional members must be created, and the flags to use for creating +those additional members. The <CODE>eoa</CODE> member caches the size of the format +address space so the family members don't have to be queried in order to find +it. + +</P> + +<PRE> +/* The description of a file belonging to this driver. */ +typedef struct H5FD_family_t { + H5FD_t pub; /*public stuff, must be first */ + hid_t memb_fapl_id; /*file access property list for members */ + hsize_t memb_size; /*maximum size of each member file */ + int nmembs; /*number of family members */ + int amembs; /*number of member slots allocated */ + H5FD_t **memb; /*dynamic array of member pointers */ + haddr_t eoa; /*end of allocated addresses */ + char *name; /*name generator printf format */ + unsigned flags; /*flags for opening additional members */ +} H5FD_family_t; +</PRE> + +<P> +<STRONG>Example:</STRONG> The sec2 driver needs to keep track of the underlying Unix +file descriptor and also the end of format address space and current Unix file +size. It also keeps track of the current file position and last operation +(read, write, or unknown) in order to optimize calls to <CODE>lseek</CODE>. The +<CODE>device</CODE> and <CODE>inode</CODE> fields are defined on Unix in order to uniquely +identify the file and will be discussed below. + +</P> + +<PRE> +typedef struct H5FD_sec2_t { + H5FD_t pub; /*public stuff, must be first */ + int fd; /*the unix file */ + haddr_t eoa; /*end of allocated region */ + haddr_t eof; /*end of file; current file size*/ + haddr_t pos; /*current file I/O position */ + int op; /*last operation */ + dev_t device; /*file device number */ + ino_t inode; /*file i-node number */ +} H5FD_sec2_t; +</PRE> + + + +<H3><A NAME="SEC10" HREF="#TOC10">Opening Files</A></H3> + +<P> +All drivers must define a function for opening/creating a file. This +function should have a prototype which is: + +</P> +<P> +<DL> +<DT><U>Function:</U> static H5FD_t * <B>open</B> <I>(const char *<VAR>name</VAR>, unsigned <VAR>flags</VAR>, hid_t <VAR>fapl</VAR>, haddr_t <VAR>maxaddr</VAR>)</I> +<DD><A NAME="IDX1"></A> + +</P> +<P> +The file name <VAR>name</VAR> and file access property list <VAR>fapl</VAR> are +the same as were specified in the <CODE>H5Fcreate</CODE> or <CODE>H5Fopen</CODE> +call. The <VAR>flags</VAR> are the same as in those calls also except the +flag <CODE>H5F_ACC_CREATE</CODE> is also present if the call was to +<CODE>H5Fcreate</CODE> and they are documented in the <TT>`H5Fpublic.h'</TT> +file. The <VAR>maxaddr</VAR> argument is the maximum format address that the +driver should be prepared to handle (the minimum address is always +zero). +</DL> + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver opens a Unix file with the requested name +and saves information which uniquely identifies the file (the Unix device +number and inode). + +</P> + +<PRE> +static H5FD_t * +H5FD_sec2_open(const char *name, unsigned flags, hid_t fapl_id/*unused*/, + haddr_t maxaddr) +{ + unsigned o_flags; + int fd; + struct stat sb; + H5FD_sec2_t *file=NULL; + + /* Check arguments */ + if (!name || !*name) return NULL; + if (0==maxaddr || HADDR_UNDEF==maxaddr) return NULL; + if (ADDR_OVERFLOW(maxaddr)) return NULL; + + /* Build the open flags */ + o_flags = (H5F_ACC_RDWR & flags) ? O_RDWR : O_RDONLY; + if (H5F_ACC_TRUNC & flags) o_flags |= O_TRUNC; + if (H5F_ACC_CREAT & flags) o_flags |= O_CREAT; + if (H5F_ACC_EXCL & flags) o_flags |= O_EXCL; + + /* Open the file */ + if ((fd=open(name, o_flags, 0666))<0) return NULL; + if (fstat(fd, &sb)<0) { + close(fd); + return NULL; + } + + /* Create the new file struct */ + file = calloc(1, sizeof(H5FD_sec2_t)); + file->fd = fd; + file->eof = sb.st_size; + file->pos = HADDR_UNDEF; + file->op = OP_UNKNOWN; + file->device = sb.st_dev; + file->inode = sb.st_ino; + + return (H5FD_t*)file; +} +</PRE> + + + +<H3><A NAME="SEC11" HREF="#TOC11">Closing Files</A></H3> + +<P> +Closing a file simply means that all cached data should be flushed to the next +lower layer, the file should be closed at the next lower layer, and all +file-related data structures should be freed. All information needed by the +close function is already present in the file handle. + +</P> +<P> +<DL> +<DT><U>Function:</U> static herr_t <B>close</B> <I>(H5FD_t *<VAR>file</VAR>)</I> +<DD><A NAME="IDX2"></A> + +</P> +<P> +The <VAR>file</VAR> argument is the handle which was returned by the <CODE>open</CODE> +function, and the <CODE>close</CODE> should free only memory associated with the +driver-specific part of the handle (the public parts will have already been released by HDF5's virtual file layer). +</DL> + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver just closes the underlying Unix file, +making sure that the actual file size is the same as that known to the +library by writing a zero to the last file position it hasn't been +written by some previous operation (which happens in the same code which +flushes the file contents and is shown below). + +</P> + +<PRE> +static herr_t +H5FD_sec2_close(H5FD_t *_file) +{ + H5FD_sec2_t *file = (H5FD_sec2_t*)_file; + + if (H5FD_sec2_flush(_file)<0) return -1; + if (close(file->fd)<0) return -1; + free(file); + return 0; +} +</PRE> + + + +<H3><A NAME="SEC12" HREF="#TOC12">File Keys</A></H3> + +<P> +Occasionally an application will attempt to open a single file more than one +time in order to obtain multiple handles to the file. HDF5 allows the files to +share information<A NAME="DOCF6" HREF="#FOOT6">(6)</A> but in order to +accomplish this HDF5 must be able to tell when two names refer to the same +file. It does this by associating a driver-defined key with each file opened +by a driver and comparing the key for an open request with the keys for all +other files currently open by the same driver. + +</P> +<P> +<DL> +<DT><U>Function:</U> const int <B>cmp</B> <I>(const H5FD_t *<VAR>f1</VAR>, const H5FD_t *<VAR>f2</VAR>)</I> +<DD><A NAME="IDX3"></A> + +</P> +<P> +The driver may provide a function which compares two files <VAR>f1</VAR> and +<VAR>f2</VAR> belonging to the same driver and returns a negative, positive, or +zero value <I>a la</I> the <CODE>strcmp</CODE> function.<A NAME="DOCF7" HREF="#FOOT7">(7)</A> If this +function is not provided then HDF5 assumes that all calls to the <CODE>open</CODE> +callback return unique files regardless of the arguments and it is up to the +application to avoid doing this if that assumption is incorrect. +</DL> + +</P> +<P> +Each time a file is opened the library calls the <CODE>cmp</CODE> function to +compare that file with all other files currently open by the same driver and +if one of them matches (at most one can match) then the file which was just +opened is closed and the previously opened file is used instead. + +</P> +<P> +Opening a file twice with incompatible flags will result in failure. For +instance, opening a file with the truncate flag is a two step process which +first opens the file without truncation so keys can be compared, and if no +matching file is found already open then the file is closed and immediately +reopened with the truncation flag set (if a matching file is already open then +the truncating open will fail). + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver uses the Unix device and i-node as the +key. They were initialized when the file was opened. + +</P> + +<PRE> +static int +H5FD_sec2_cmp(const H5FD_t *_f1, const H5FD_t *_f2) +{ + const H5FD_sec2_t *f1 = (const H5FD_sec2_t*)_f1; + const H5FD_sec2_t *f2 = (const H5FD_sec2_t*)_f2; + + if (f1->device < f2->device) return -1; + if (f1->device > f2->device) return 1; + + if (f1->inode < f2->inode) return -1; + if (f1->inode > f2->inode) return 1; + + return 0; +} +</PRE> + + + +<H3><A NAME="SEC13" HREF="#TOC13">Saving Modes Across Opens</A></H3> + +<P> +Some drivers may also need to store certain information in the file superblock +in order to be able to reliably open the file at a later date. This is done by +three functions: one to determine how much space will be necessary to store +the information in the superblock, one to encode the information, and one to +decode the information. These functions are optional, but if any one is +defined then the other two must also be defined. + +</P> +<P> +<DL> +<DT><U>Function:</U> static hsize_t <B>sb_size</B> <I>(H5FD_t *<VAR>file</VAR>)</I> +<DD><A NAME="IDX4"></A> +<DT><U>Function:</U> static herr_t <B>sb_encode</B> <I>(H5FD_t *<VAR>file</VAR>, char *<VAR>name</VAR>, unsigned char *<VAR>buf</VAR>)</I> +<DD><A NAME="IDX5"></A> +<DT><U>Function:</U> static herr_t <B>sb_decode</B> <I>(H5FD_t *<VAR>file</VAR>, const char *<VAR>name</VAR>, const unsigned char *<VAR>buf</VAR>)</I> +<DD><A NAME="IDX6"></A> + +</P> +<P> +The <CODE>sb_size</CODE> function returns the number of bytes necessary to encode +information needed later if the file is reopened. The <CODE>sb_encode</CODE> +function encodes information from the file into buffer <VAR>buf</VAR> +allocated by the caller. It also writes an 8-character (plus null +termination) into the <CODE>name</CODE> argument, which should be a unique +identification for the driver. The <CODE>sb_decode</CODE> function looks at +the <VAR>name</VAR> + +</P> +<P> + decodes +data from the buffer <VAR>buf</VAR> and updates the <VAR>file</VAR> argument with the new information, +advancing <VAR>*p</VAR> in the process. +</DL> + +</P> +<P> +The part of this which is somewhat tricky is that the file must be readable +before the superblock information is decoded. File access modes fall outside +the scope of the HDF5 file format, but they are placed inside the boot block +for convenience.<A NAME="DOCF8" HREF="#FOOT8">(8)</A> + +</P> +<P> +<STRONG>Example:</STRONG> <EM>To be written later.</EM> + +</P> + + +<H2><A NAME="SEC14" HREF="#TOC14">Address Space Functions</A></H2> + +<P> +HDF5 does not assume that a file is a linear address space of bytes. Instead, +the library will call functions to allocate and free portions of the HDF5 +format address space, which in turn map onto functions in the file driver to +allocate and free portions of file address space. The library tells the file +driver how much format address space it wants to allocate and the driver +decides what format address to use and how that format address is mapped onto +the file address space. Usually the format address is chosen so that the file +address can be calculated in constant time for data I/O operations (which are +always specified by format addresses). + +</P> + + + +<H3><A NAME="SEC15" HREF="#TOC15">Userblock and Superblock</A></H3> + +<P> +The HDF5 format allows an optional userblock to appear before the actual HDF5 +data in such a way that if the userblock is <STRONG>sucked out</STRONG> of the file and +everything remaining is shifted downward in the file address space, then the +file is still a valid HDF5 file. The userblock size can be zero or any +multiple of two greater than or equal to 512 and the file superblock begins +immediately after the userblock. + +</P> +<P> +HDF5 allocates space for the userblock and superblock by calling an +allocation function defined below, which must return a chunk of memory at +format address zero on the first call. + +</P> + + +<H3><A NAME="SEC16" HREF="#TOC16">Allocation of Format Regions</A></H3> + +<P> +The library makes many types of allocation requests: + +</P> +<DL COMPACT> + +<DT><CODE>H5FD_MEM_SUPER</CODE> +<DD> +An allocation request for the userblock and/or superblock. +<DT><CODE>H5FD_MEM_BTREE</CODE> +<DD> +An allocation request for a node of a B-tree. +<DT><CODE>H5FD_MEM_DRAW</CODE> +<DD> +An allocation request for the raw data of a dataset. +<DT><CODE>H5FD_MEM_META</CODE> +<DD> +An allocation request for the raw data of a dataset which +the user has indicated will be relatively small. +<DT><CODE>H5FD_MEM_GROUP</CODE> +<DD> +An allocation request for a group leaf node (internal nodes of the group tree +are allocated as H5MF_BTREE). +<DT><CODE>H5FD_MEM_GHEAP</CODE> +<DD> +An allocation request for a global heap collection. Global heaps are used to +store certain types of references such as dataset region references. The set +of all global heap collections can become quite large. +<DT><CODE>H5FD_MEM_LHEAP</CODE> +<DD> +An allocation request for a local heap. Local heaps are used to store the +names which are members of a group. The combined size of all local heaps is a +function of the number of object names in the file. +<DT><CODE>H5FD_MEM_OHDR</CODE> +<DD> +An allocation request for (part of) an object header. Object headers are +relatively small and include meta information about objects (like the data +space and type of a dataset) and attributes. +</DL> + +<P> +When a chunk of memory is freed the library adds it to a free list and +allocation requests are satisfied from the free list before requesting memory +from the file driver. Each type of allocation request enumerated above has its +own free list, but the file driver can specify that certain object types can +share a free list. It does so by providing an array which maps a request type +to a free list. If any value of the map is <CODE>H5MF_DEFAULT</CODE> (zero) then the +object's own free list is used. The special value <CODE>H5MF_NOLIST</CODE> indicates +that the library should not attempt to maintain a free list for that +particular object type, instead calling the file driver each time an object of +that type is freed. + +</P> +<P> +Mappings predefined in the <TT>`H5FDpublic.h'</TT> file are: +<DL COMPACT> + +<DT><CODE>H5FD_FLMAP_SINGLE</CODE> +<DD> +All memory usage types are mapped to a single free list. +<DT><CODE>H5FD_FLMAP_DICHOTOMY</CODE> +<DD> +Memory usage is segregated into meta data and raw data for the purposes of +memory management. +<DT><CODE>H5FD_FLMAP_DEFAULT</CODE> +<DD> +Each memory usage type has its own free list. +</DL> + +<P> +<STRONG>Example:</STRONG> To make a map that manages object headers on one free list +and everything else on another free list one might initialize the map with the +following code: (the use of <CODE>H5FD_MEM_SUPER</CODE> is arbitrary) + +</P> + +<PRE> +H5FD_mem_t mt, map[H5FD_MEM_NTYPES]; + +for (mt=0; mt<H5FD_MEM_NTYPES; mt++) { + map[mt] = (H5FD_MEM_OHDR==mt) ? mt : H5FD_MEM_SUPER; +} +</PRE> + +<P> +If an allocation request cannot be satisfied from the free list then one of +two things happen. If the driver defines an allocation callback then it is +used to allocate space; otherwise new memory is allocated from the end of the +format address space by incrementing the end-of-address marker. + +</P> +<P> +<DL> +<DT><U>Function:</U> static haddr_t <B>alloc</B> <I>(H5FD_t *<VAR>file</VAR>, H5MF_type_t <VAR>type</VAR>, hsize_t <VAR>size</VAR>)</I> +<DD><A NAME="IDX7"></A> + +</P> +<P> +The <VAR>file</VAR> argument is the file from which space is to be allocated, +<VAR>type</VAR> is the type of memory being requested (from the list above) without +being mapped according to the freelist map and <VAR>size</VAR> is the number of +bytes being requested. The library is allowed to allocate large chunks of +storage and manage them in a layer above the file driver (although the current +library doesn't do that). The allocation function should return a format +address for the first byte allocated. The allocated region extends from that +address for <VAR>size</VAR> bytes. If the request cannot be honored then the +undefined address value is returned (<CODE>HADDR_UNDEF</CODE>). The first call to +this function for a file which has never had memory allocated <EM>must</EM> +return a format address of zero or <CODE>HADDR_UNDEF</CODE> since this is how the +library allocates space for the userblock and/or superblock. +</DL> + +</P> + +<P> +<STRONG>Example:</STRONG> <EM>To be written later.</EM> + +</P> + + +<H3><A NAME="SEC17" HREF="#TOC17">Freeing Format Regions</A></H3> + +<P> +When the library is finished using a certain region of the format address +space it will return the space to the free list according to the type of +memory being freed and the free list map described above. If the free list has +been disabled for a particular memory usage type (according to the free list +map) and the driver defines a <CODE>free</CODE> callback then it will be +invoked. The <CODE>free</CODE> callback is also invoked for all entries on the free +list when the file is closed. + +</P> +<P> +<DL> +<DT><U>Function:</U> static herr_t <B>free</B> <I>(H5FD_t *<VAR>file</VAR>, H5MF_type_t <VAR>type</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>)</I> +<DD><A NAME="IDX8"></A> + +</P> +<P> +The <VAR>file</VAR> argument is the file for which space is being freed; <VAR>type</VAR> +is the type of object being freed (from the list above) without being mapped +according to the freelist map; <VAR>addr</VAR> is the first format address to free; +and <VAR>size</VAR> is the size in bytes of the region being freed. The region +being freed may refer to just part of the region originally allocated and/or +may cross allocation boundaries provided all regions being freed have the same +usage type. However, the library will never attempt to free regions which have +already been freed or which have never been allocated. +</DL> + +</P> +<P> +A driver may choose to not define the <CODE>free</CODE> function, in which case +format addresses will be leaked. This isn't normally a huge problem since the +library contains a simple free list of its own and freeing parts of the format +address space is not a common occurrence. + +</P> +<P> +<STRONG>Example:</STRONG> <EM>To be written later.</EM> + +</P> + + +<H3><A NAME="SEC18" HREF="#TOC18">Querying Address Range</A></H3> + +<P> +Each file driver must have some mechanism for setting and querying the end of +address, or <STRONG>EOA</STRONG>, marker. The EOA marker is the first format address +after the last format address ever allocated. If the last part of the +allocated address range is freed then the driver may optionally decrease the +eoa marker. + +</P> +<P> +<DL> +<DT><U>Function:</U> static haddr_t <B>get_eoa</B> <I>(H5FD_t *<VAR>file</VAR>)</I> +<DD><A NAME="IDX9"></A> + +</P> +<P> +This function returns the current value of the EOA marker for the specified +file. +</DL> + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver just returns the current eoa marker value +which is cached in the file structure: + +</P> + +<PRE> +static haddr_t +H5FD_sec2_get_eoa(H5FD_t *_file) +{ + H5FD_sec2_t *file = (H5FD_sec2_t*)_file; + return file->eoa; +} +</PRE> + +<P> +The eoa marker is initially zero when a file is opened and the library may set +it to some other value shortly after the file is opened (after the superblock +is read and the saved eoa marker is determined) or when allocating additional +memory in the absence of an <CODE>alloc</CODE> callback (described above). + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver simply caches the eoa marker in the file +structure and does not extend the underlying Unix file. When the file is +flushed or closed then the Unix file size is extended to match the eoa marker. + +</P> + +<PRE> +static herr_t +H5FD_sec2_set_eoa(H5FD_t *_file, haddr_t addr) +{ + H5FD_sec2_t *file = (H5FD_sec2_t*)_file; + file->eoa = addr; + return 0; +} +</PRE> + + + +<H2><A NAME="SEC19" HREF="#TOC19">Data Functions</A></H2> + +<P> +These functions operate on data, transferring a region of the format address +space between memory and files. + +</P> + + + +<H3><A NAME="SEC20" HREF="#TOC20">Contiguous I/O Functions</A></H3> + +<P> +A driver must specify two functions to transfer data from the library to the +file and vice versa. + +</P> +<P> +<DL> +<DT><U>Function:</U> static herr_t <B>read</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, void *<VAR>buf</VAR>)</I> +<DD><A NAME="IDX10"></A> +<DT><U>Function:</U> static herr_t <B>write</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, const void *<VAR>buf</VAR>)</I> +<DD><A NAME="IDX11"></A> + +</P> +<P> +The <CODE>read</CODE> function reads data from file <VAR>file</VAR> beginning at address +<VAR>addr</VAR> and continuing for <VAR>size</VAR> bytes into the buffer <VAR>buf</VAR> +supplied by the caller. The <CODE>write</CODE> function transfers data in the +opposite direction. Both functions take a data transfer property list +<VAR>dxpl</VAR> which indicates the fine points of how the data is to be +transferred and which comes directly from the <CODE>H5Dread</CODE> or +<CODE>H5Dwrite</CODE> function. Both functions receive <VAR>type</VAR> of +data being written, which may allow a driver to tune it's behavior for +different kinds of data. +</DL> + +</P> +<P> +Both functions should return a negative value if they fail to transfer the +requested data, or non-negative if they succeed. The library will never +attempt to read from unallocated regions of the format address space. + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver just makes system calls. It tries not to +call <CODE>lseek</CODE> if the current operation is the same as the previous +operation and the file position is correct. It also fills the output buffer +with zeros when reading between the current EOF and EOA markers and restarts +system calls which were interrupted. + +</P> + +<PRE> +static herr_t +H5FD_sec2_read(H5FD_t *_file, H5FD_mem_t type/*unused*/, hid_t dxpl_id/*unused*/, + haddr_t addr, hsize_t size, void *buf/*out*/) +{ + H5FD_sec2_t *file = (H5FD_sec2_t*)_file; + ssize_t nbytes; + + assert(file && file->pub.cls); + assert(buf); + + /* Check for overflow conditions */ + if (REGION_OVERFLOW(addr, size)) return -1; + if (addr+size>file->eoa) return -1; + + /* Seek to the correct location */ + if ((addr!=file->pos || OP_READ!=file->op) && + file_seek(file->fd, (file_offset_t)addr, SEEK_SET)<0) { + file->pos = HADDR_UNDEF; + file->op = OP_UNKNOWN; + return -1; + } + + /* + * Read data, being careful of interrupted system calls, partial results, + * and the end of the file. + */ + while (size>0) { + do nbytes = read(file->fd, buf, size); + while (-1==nbytes && EINTR==errno); + if (-1==nbytes) { + /* error */ + file->pos = HADDR_UNDEF; + file->op = OP_UNKNOWN; + return -1; + } + if (0==nbytes) { + /* end of file but not end of format address space */ + memset(buf, 0, size); + size = 0; + } + assert(nbytes>=0); + assert((hsize_t)nbytes<=size); + size -= (hsize_t)nbytes; + addr += (haddr_t)nbytes; + buf = (char*)buf + nbytes; + } + + /* Update current position */ + file->pos = addr; + file->op = OP_READ; + return 0; +} +</PRE> + +<P> +<STRONG>Example:</STRONG> The sec2 <CODE>write</CODE> callback is similar except it updates +the file EOF marker when extending the file. + +</P> + + +<H3><A NAME="SEC21" HREF="#TOC21">Flushing Cached Data</A></H3> + +<P> +Some drivers may desire to cache data in memory in order to make larger I/O +requests to the underlying file and thus improving bandwidth. Such drivers +should register a cache flushing function so that the library can insure that +data has been flushed out of the drivers in response to the application +calling <CODE>H5Fflush</CODE>. + +</P> +<P> +<DL> +<DT><U>Function:</U> static herr_t <B>flush</B> <I>(H5FD_t *<VAR>file</VAR>)</I> +<DD><A NAME="IDX12"></A> + +</P> +<P> +Flush all data for file <VAR>file</VAR> to storage. +</DL> + +</P> +<P> +<STRONG>Example:</STRONG> The sec2 driver doesn't cache any data but it also doesn't +extend the Unix file as agressively as it should. Therefore, when finalizing a +file it should write a zero to the last byte of the allocated region so that +when reopening the file later the EOF marker will be at least as large as the +EOA marker saved in the superblock (otherwise HDF5 will refuse to open the +file, claiming that the data appears to be truncated). + +</P> + +<PRE> +static herr_t +H5FD_sec2_flush(H5FD_t *_file) +{ + H5FD_sec2_t *file = (H5FD_sec2_t*)_file; + + if (file->eoa>file->eof) { + if (-1==file_seek(file->fd, file->eoa-1, SEEK_SET)) return -1; + if (write(file->fd, "", 1)!=1) return -1; + file->eof = file->eoa; + file->pos = file->eoa; + file->op = OP_WRITE; + } + + return 0; +} +</PRE> + + + +<H2><A NAME="SEC22" HREF="#TOC22">Optimization Functions</A></H2> + +<P> +The library is capable of performing several generic optimizations on I/O, but +these types of optimizations may not be appropriate for a given VFL driver. +</P> + +<P> +Each driver may provide a query function to allow the library to query whether +to enable these optimizations. If a driver lacks a query function, the library +will disable all types of optimizations which can be queried. +</P> + +<P> +<DL> +<DT><U>Function:</U> static herr_t <B>query</B> <I>(const H5FD_t *<VAR>file</VAR>, unsigned long *<VAR>flags</VAR>)</I> +<DD><A NAME="IDX17"></A> +</P> +<P> +This function is called by the library to query which optimizations to enable +for I/O to this driver. These are the flags which are currently defined: + +<UL> +<DL> +<DT>H5FD_FEAT_AGGREGATE_METADATA (0x00000001) +<DD>Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that +the library will attempt to allocate a larger block for metadata and +then sub-allocate each metadata request from that larger block. +<DT>H5FD_FEAT_ACCUMULATE_METADATA (0x00000002) +<DD>Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that +the library will attempt to cache metadata as it is written to the file +and build up a larger block of metadata to eventually pass to the VFL +'write' routine. +<DT>H5FD_FEAT_DATA_SIEVE (0x00000004) +<DD>Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that +the library will attempt to cache raw data as it is read from/written to +a file in a "data sieve" buffer. See Rajeev Thakur's papers: + <UL> + <DL> + <DT>http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz + <DT>http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz + </DL> + </UL> +</DL> +</UL> +</P> + +</DL> +</P> + +<H2><A NAME="SEC23" HREF="#TOC23">Registration of a Driver</A></H2> + +<P> +Before a driver can be used the HDF5 library needs to be told of its +existence. This is done by registering the driver, which results in a driver +identification number. Instead of passing many arguments to the registration +function, the driver information is entered into a structure and the address +of the structure is passed to the registration function where it is +copied. This allows the HDF5 API to be extended while providing backward +compatibility at the source level. + +</P> +<P> +<DL> +<DT><U>Function:</U> hid_t <B>H5FDregister</B> <I>(H5FD_class_t *<VAR>cls</VAR>)</I> +<DD><A NAME="IDX13"></A> + +</P> +<P> +The driver described by struct <VAR>cls</VAR> is registered with the library and an +ID number for the driver is returned. +</DL> + +</P> +<P> +The <CODE>H5FD_class_t</CODE> type is a struct with the following fields: + +</P> +<DL COMPACT> + +<DT><CODE>const char *name</CODE> +<DD> +A pointer to a constant, null-terminated driver name to be used for debugging +purposes. +<DT><CODE>size_t fapl_size</CODE> +<DD> +The size in bytes of the file access mode structure or zero if the driver +supplies a copy function or doesn't define the structure. +<DT><CODE>void *(*fapl_copy)(const void *fapl)</CODE> +<DD> +An optional function which copies a driver-defined file access mode structure. +This field takes precedence over <CODE>fm_size</CODE> when both are defined. +<DT><CODE>void (*fapl_free)(void *fapl)</CODE> +<DD> +An optional function to free the driver-defined file access mode structure. If +null, then the library calls the C <CODE>free</CODE> function to free the +structure. +<DT><CODE>size_t dxpl_size</CODE> +<DD> +The size in bytes of the data transfer mode structure or zero if the driver +supplies a copy function or doesn't define the structure. +<DT><CODE>void *(*dxpl_copy)(const void *dxpl)</CODE> +<DD> +An optional function which copies a driver-defined data transfer mode +structure. This field takes precedence over <CODE>xm_size</CODE> when both are +defined. +<DT><CODE>void (*dxpl_free)(void *dxpl)</CODE> +<DD> +An optional function to free the driver-defined data transfer mode +structure. If null, then the library calls the C <CODE>free</CODE> function to +free the structure. +<DT><CODE>H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr)</CODE> +<DD> +The function which opens or creates a new file. +<DT><CODE>herr_t (*close)(H5FD_t *file)</CODE> +<DD> +The function which ends access to a file. +<DT><CODE>int (*cmp)(const H5FD_t *f1, const H5FD_t *f2)</CODE> +<DD> +An optional function to determine whether two open files have the same key. If +this function is not present then the library assumes that two files will +never be the same. +<DT><CODE>int (*query)(const H5FD_t *f, unsigned long *flags)</CODE> +<DD> +An optional function to determine which library optimizations a driver can +support. +<DT><CODE>haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hsize_t size)</CODE> +<DD> +An optional function to allocate space in the file. +<DT><CODE>herr_t (*free)(H5FD_t *file, H5FD_mem_t type, haddr_t addr, hsize_t size)</CODE> +<DD> +An optional function to free space in the file. +<DT><CODE>haddr_t (*get_eoa)(H5FD_t *file)</CODE> +<DD> +A function to query how much of the format address space has been allocated. +<DT><CODE>herr_t (*set_eoa)(H5FD_t *file, haddr_t)</CODE> +<DD> +A function to set the end of address space. +<DT><CODE>haddr_t (*get_eof)(H5FD_t *file)</CODE> +<DD> +A function to return the current end-of-file marker value. +<DT><CODE>herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, void *buffer)</CODE> +<DD> +A function to read data from a file. +<DT><CODE>herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, const void *buffer)</CODE> +<DD> +A function to write data to a file. +<DT><CODE>herr_t (*flush)(H5FD_t *file)</CODE> +<DD> +A function which flushes cached data to the file. +<DT><CODE>H5FD_mem_t fl_map[H5FD_MEM_NTYPES]</CODE> +<DD> +An array which maps a file allocation request type to a free list. +</DL> + +<P> +<STRONG>Example:</STRONG> The sec2 driver would be registered as: + +</P> + +<PRE> +static const H5FD_class_t H5FD_sec2_g = { + "sec2", /*name */ + MAXADDR, /*maxaddr */ + NULL, /*sb_size */ + NULL, /*sb_encode */ + NULL, /*sb_decode */ + 0, /*fapl_size */ + NULL, /*fapl_get */ + NULL, /*fapl_copy */ + NULL, /*fapl_free */ + 0, /*dxpl_size */ + NULL, /*dxpl_copy */ + NULL, /*dxpl_free */ + H5FD_sec2_open, /*open */ + H5FD_sec2_close, /*close */ + H5FD_sec2_cmp, /*cmp */ + H5FD_sec2_query, /*query */ + NULL, /*alloc */ + NULL, /*free */ + H5FD_sec2_get_eoa, /*get_eoa */ + H5FD_sec2_set_eoa, /*set_eoa */ + H5FD_sec2_get_eof, /*get_eof */ + H5FD_sec2_read, /*read */ + H5FD_sec2_write, /*write */ + H5FD_sec2_flush, /*flush */ + H5FD_FLMAP_SINGLE, /*fl_map */ +}; + +hid_t +H5FD_sec2_init(void) +{ + if (!H5FD_SEC2_g) { + H5FD_SEC2_g = H5FDregister(&H5FD_sec2_g); + } + return H5FD_SEC2_g; +} +</PRE> + +<P> +A driver can be removed from the library by unregistering it + +</P> +<P> +<DL> +<DT><U>Function:</U> herr_t <B>H5Dunregister</B> <I>(hid_t <VAR>driver</VAR>)</I> +<DD><A NAME="IDX14"></A> +Where <VAR>driver</VAR> is the ID number returned when the driver was registered. +</DL> + +</P> +<P> +Unregistering a driver makes it unusable for creating new file access or data +transfer property lists but doesn't affect any property lists or files that +already use that driver. + +</P> + + + + +<H3><A NAME="SECProgNote" HREF="#TOCProgNote">Programming Note +for C++ Developers Using C Functions</A></H3> + +<p>If a C routine that takes a function pointer as an argument is +called from within C++ code, the C routine should be returned from +normally. </p> + +<p>Examples of this kind of routine include callbacks such as +<code>H5Pset_elink_cb</code> and <code>H5Pset_type_conv_cb</code> +and functions such as <code>H5Tconvert</code> and +<code>H5Ewalk2</code>.</p> + +<p>Exiting the routine in its normal fashion allows the HDF5 C +Library to clean up its work properly. In other words, if the C++ +application jumps out of the routine back to the C++ +“catch” statement, the library is not given the +opportunity to close any temporary data structures that were set +up when the routine was called. The C++ application should save +some state as the routine is started so that any problem that +occurs might be diagnosed.</p> + + + + + + + +<H2><A NAME="SEC24" HREF="#TOC24">Querying Driver Information</A></H2> + +<P> +<DL> +<DT><U>Function:</U> void * <B>H5Pget_driver_data</B> <I>(hid_t <VAR>fapl</VAR>)</I> +<DD><A NAME="IDX15"></A> +<DT><U>Function:</U> void * <B>H5Pget_driver_data</B> <I>(hid_t <VAR>fxpl</VAR>)</I> +<DD><A NAME="IDX16"></A> + +</P> +<P> +This function is intended to be used by driver functions, not applications. +It returns a pointer directly into the file access property list +<CODE><VAR>fapl</VAR></CODE> which is a copy of the driver's file access mode originally +provided to the <CODE>H5Pset_driver</CODE> function. If its argument is a data +transfer property list <CODE>fxpl</CODE> then it returns a pointer to the +driver-specific data transfer information instead. +</DL> + +</P> + + + +<H1><A NAME="SEC25" HREF="#TOC25">Miscellaneous</A></H1> + +<P> +The various private <CODE>H5F_low_*</CODE> functions will be replaced by public +<CODE>H5FD*</CODE> functions so they can be called from drivers. + +</P> +<P> +All private functions <CODE>H5F_addr_*</CODE> which operate on addresses will be +renamed as public functions by removing the first underscore so they can be +called by drivers. + +</P> +<P> +The <CODE>haddr_t</CODE> address data type will be passed by value throughout the +library. The original intent was that this type would eventually be a union of +file address types for the various drivers and may become quite large, but +that was back when drivers were part of HDF5. It will become an alias for an +unsigned integer type (32 or 64 bits depending on how the library was +configured). + +</P> +<P> +The various <CODE>H5F*.c</CODE> driver files will be renamed <CODE>H5FD*.c</CODE> and each +will have a corresponding header file. All driver functions except the +initializer and API will be declared static. + +</P> +<P> +This documentation didn't cover optimization functions which would be useful +to drivers like MPI-IO. Some drivers may be able to perform data pipeline +operations more efficiently than HDF5 and need to be given a chance to +override those parts of the pipeline. The pipeline would be designed to call +various H5FD optimization functions at various points which return one of +three values: the operation is not implemented by the driver, the operation is +implemented but failed in a non-recoverable manner, the operation is +implemented and succeeded. + +</P> +<P> +Various parts of HDF5 check the only the top-level file driver and do +something special if it is the MPI-IO driver. However, we might want to be +able to put the MPI-IO driver under other drivers such as the raw part of a +split driver or under a debug driver whose sole purpose is to accumulate +statistics as it passes all requests through to the MPI-IO driver. Therefore +we will probably need a function which takes a format address and or object +type and returns the driver which would have been used at the lowest level to +process the request. + +</P> + +<P><HR><P> +<H1>Footnotes</H1> +<H3><A NAME="FOOT1" HREF="#DOCF1">(1)</A></H3> +<P>The driver name is by convention and might +not apply to drivers which are not distributed with HDF5. +<H3><A NAME="FOOT2" HREF="#DOCF2">(2)</A></H3> +<P>The access method also indicates how to translate +the storage name to a storage server such as a file, network protocol, or +memory. +<H3><A NAME="FOOT3" HREF="#DOCF3">(3)</A></H3> +<P>The term +"<EM>file</EM> access property list" is a misnomer since storage isn't +required to be a file. +<H3><A NAME="FOOT4" HREF="#DOCF4">(4)</A></H3> +<P>This +function is overloaded to operate on data transfer property lists also, as +described below. +<H3><A NAME="FOOT5" HREF="#DOCF5">(5)</A></H3> +<P>Read-only access is only appropriate when opening an existing +file. +<H3><A NAME="FOOT6" HREF="#DOCF6">(6)</A></H3> +<P>For instance, writing data to one handle will cause +the data to be immediately visible on the other handle. +<H3><A NAME="FOOT7" HREF="#DOCF7">(7)</A></H3> +<P>The ordering is +arbitrary as long as it's consistent within a particular file driver. +<H3><A NAME="FOOT8" HREF="#DOCF8">(8)</A></H3> +<P>File access modes do not describe data, but rather +describe how the HDF5 format address space is mapped to the underlying +file(s). Thus, in general the mapping must be known before the file superblock +can be read. However, the user usually knows enough about the mapping for the +superblock to be readable and once the superblock is read the library can fill +in the missing parts of the mapping. +<P><HR><P> + +<?php include("../ed_libs/Footer2.htm"); ?> + +</BODY> +</HTML> diff --git a/doxygen/hdf5_footer.html b/doxygen/hdf5_footer.html new file mode 100644 index 0000000..520f3f5 --- /dev/null +++ b/doxygen/hdf5_footer.html @@ -0,0 +1,21 @@ +<!-- start footer part --> +<!--BEGIN GENERATE_TREEVIEW--> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + $navpath + <li class="footer">$generatedby + <a href="http://www.doxygen.org/index.html"> + <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li> + </ul> +</div> +<!--END GENERATE_TREEVIEW--> +<!--BEGIN !GENERATE_TREEVIEW--> +<hr class="footer"/><address class="footer"><small> +$generatedby  <a href="http://www.doxygen.org/index.html"> +<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/> +</a> $doxygenversion +</small></address> +<!--END !GENERATE_TREEVIEW--> + +</body> +</html> diff --git a/doxygen/hdf5_header.html b/doxygen/hdf5_header.html new file mode 100644 index 0000000..4a575d6 --- /dev/null +++ b/doxygen/hdf5_header.html @@ -0,0 +1,61 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen $doxygenversion"/> +<meta name="viewport" content="width=device-width, initial-scale=1"/> +<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME--> +<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME--> +<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="$relpath^jquery.js"></script> +<script type="text/javascript" src="$relpath^dynsections.js"></script> +$treeview +$search +$mathjax +<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" /> +<link href="$relpath$hdf5doxy.css" rel="stylesheet" type="text/css"> +<!-- $extrastylesheet --> +<script type="text/javascript" src="$relpath$hdf5_navtree_hacks.js"></script> + +</head> +<body> + +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better know about our user community by answering the following short survey: <a href="https://www.hdfgroup.org/">https://www.hdfgroup.org/</a></div> + +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> + +<!--BEGIN TITLEAREA--> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <!--BEGIN PROJECT_LOGO--> + <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td> + <!--END PROJECT_LOGO--> + <!--BEGIN PROJECT_NAME--> + <td id="projectalign" style="padding-left: 0.5em;"> + <div id="projectname"><a href="https://www.hdfgroup.org">$projectname</a> + <!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER--> + </div> + <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF--> + </td> + <!--END PROJECT_NAME--> + <!--BEGIN !PROJECT_NAME--> + <!--BEGIN PROJECT_BRIEF--> + <td id="projectalign" style="padding-left: 0.5em;"> + <div id="projectbrief">$projectbrief</div> + </td> + <!--END PROJECT_BRIEF--> + <!--END !PROJECT_NAME--> + <!--BEGIN DISABLE_INDEX--> + <!--BEGIN SEARCHENGINE--> + <td>$searchbox</td> + <!--END SEARCHENGINE--> + <!--END DISABLE_INDEX--> + </tr> + </tbody> +</table> +</div> +<!--END TITLEAREA--> +<!-- end header part --> diff --git a/doxygen/hdf5_navtree_hacks.js b/doxygen/hdf5_navtree_hacks.js new file mode 100644 index 0000000..942970c --- /dev/null +++ b/doxygen/hdf5_navtree_hacks.js @@ -0,0 +1,246 @@ + +// generate a table of contents in the side-nav based on the h1/h2 tags of the current page. +function generate_autotoc() { + var headers = $("h1, h2"); + if(headers.length > 1) { + var toc = $("#side-nav").append('<div id="nav-toc" class="toc"><h3>Table of contents</h3></div>'); + toc = $("#nav-toc"); + var footer = $("#nav-path"); + var footerHeight = footer.height(); + toc = toc.append('<ul></ul>'); + toc = toc.find('ul'); + var indices = new Array(); + indices[0] = 0; + indices[1] = 0; + + var h1counts = $("h1").length; + headers.each(function(i) { + var current = $(this); + var levelTag = current[0].tagName.charAt(1); + if(h1counts==0) + levelTag--; + var cur_id = current.attr("id"); + + indices[levelTag-1]+=1; + var prefix = indices[0]; + if (levelTag >1) { + prefix+="."+indices[1]; + } + + // Uncomment to add number prefixes + // current.html(prefix + " " + current.html()); + for(var l = levelTag; l < 2; ++l){ + indices[l] = 0; + } + + if(cur_id == undefined) { + current.attr('id', 'title' + i); + current.addClass('anchor'); + toc.append("<li class='level" + levelTag + "'><a id='link" + i + "' href='#title" + + i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>"); + } else { + toc.append("<li class='level" + levelTag + "'><a id='" + cur_id + "' href='#title" + + i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>"); + } + }); + resizeHeight(); + } +} + + +var global_navtree_object; + +// Overloaded to remove links to sections/subsections +function getNode(o, po) +{ + po.childrenVisited = true; + var l = po.childrenData.length-1; + for (var i in po.childrenData) { + var nodeData = po.childrenData[i]; + if((!nodeData[1]) || (nodeData[1].indexOf('#')==-1)) // <- we added this line + po.children[i] = newNode(o, po, nodeData[0], nodeData[1], nodeData[2], i==l); + } +} + +// Overloaded to adjust the size of the navtree wrt the toc +function resizeHeight() +{ + var header = $("#top"); + var sidenav = $("#side-nav"); + var content = $("#doc-content"); + var navtree = $("#nav-tree"); + var footer = $("#nav-path"); + var toc = $("#nav-toc"); + + var headerHeight = header.outerHeight(); + var footerHeight = footer.outerHeight(); + var tocHeight = toc.height(); + var windowHeight = $(window).height() - headerHeight - footerHeight; + content.css({height:windowHeight + "px"}); + navtree.css({height:(windowHeight-tocHeight) + "px"}); + sidenav.css({height:windowHeight + "px"}); +} + +// Overloaded to save the root node into global_navtree_object +function initNavTree(toroot,relpath) +{ + var o = new Object(); + global_navtree_object = o; // <- we added this line + o.toroot = toroot; + o.node = new Object(); + o.node.li = document.getElementById("nav-tree-contents"); + o.node.childrenData = NAVTREE; + o.node.children = new Array(); + o.node.childrenUL = document.createElement("ul"); + o.node.getChildrenUL = function() { return o.node.childrenUL; }; + o.node.li.appendChild(o.node.childrenUL); + o.node.depth = 0; + o.node.relpath = relpath; + o.node.expanded = false; + o.node.isLast = true; + o.node.plus_img = document.createElement("img"); + o.node.plus_img.src = relpath+"ftv2pnode.png"; + o.node.plus_img.width = 16; + o.node.plus_img.height = 22; + + if (localStorageSupported()) { + var navSync = $('#nav-sync'); + if (cachedLink()) { + showSyncOff(navSync,relpath); + navSync.removeClass('sync'); + } else { + showSyncOn(navSync,relpath); + } + navSync.click(function(){ toggleSyncButton(relpath); }); + } + + navTo(o,toroot,window.location.hash,relpath); + + $(window).bind('hashchange', function(){ + if (window.location.hash && window.location.hash.length>1){ + var a; + if ($(location).attr('hash')){ + var clslink=stripPath($(location).attr('pathname'))+':'+ + $(location).attr('hash').substring(1); + a=$('.item a[class$="'+clslink+'"]'); + } + if (a==null || !$(a).parent().parent().hasClass('selected')){ + $('.item').removeClass('selected'); + $('.item').removeAttr('id'); + } + var link=stripPath2($(location).attr('pathname')); + navTo(o,link,$(location).attr('hash'),relpath); + } else if (!animationInProgress) { + $('#doc-content').scrollTop(0); + $('.item').removeClass('selected'); + $('.item').removeAttr('id'); + navTo(o,toroot,window.location.hash,relpath); + } + }) + + $(window).on("load", showRoot); +} + +// return false if the the node has no children at all, or has only section/subsection children +function checkChildrenData(node) { + if (!(typeof(node.childrenData)==='string')) { + for (var i in node.childrenData) { + var url = node.childrenData[i][1]; + if(url.indexOf("#")==-1) + return true; + } + return false; + } + return (node.childrenData); +} + +// Modified to: +// 1 - remove the root node +// 2 - remove the section/subsection children +function createIndent(o,domNode,node,level) +{ + var level=-2; // <- we replaced level=-1 by level=-2 + var n = node; + while (n.parentNode) { level++; n=n.parentNode; } + if (checkChildrenData(node)) { // <- we modified this line to use checkChildrenData(node) instead of node.childrenData + var imgNode = document.createElement("span"); + imgNode.className = 'arrow'; + imgNode.style.paddingLeft=(16*level).toString()+'px'; + imgNode.innerHTML=arrowRight; + node.plus_img = imgNode; + node.expandToggle = document.createElement("a"); + node.expandToggle.href = "javascript:void(0)"; + node.expandToggle.onclick = function() { + if (node.expanded) { + $(node.getChildrenUL()).slideUp("fast"); + node.plus_img.innerHTML=arrowRight; + node.expanded = false; + } else { + expandNode(o, node, false, false); + } + } + node.expandToggle.appendChild(imgNode); + domNode.appendChild(node.expandToggle); + } else { + var span = document.createElement("span"); + span.className = 'arrow'; + span.style.width = 16*(level+1)+'px'; + span.innerHTML = ' '; + domNode.appendChild(span); + } +} + +// Overloaded to automatically expand the selected node +function selectAndHighlight(hash,n) +{ + var a; + if (hash) { + var link=stripPath($(location).attr('pathname'))+':'+hash.substring(1); + a=$('.item a[class$="'+link+'"]'); + } + if (a && a.length) { + a.parent().parent().addClass('selected'); + a.parent().parent().attr('id','selected'); + highlightAnchor(); + } else if (n) { + $(n.itemDiv).addClass('selected'); + $(n.itemDiv).attr('id','selected'); + } + if ($('#nav-tree-contents .item:first').hasClass('selected')) { + $('#nav-sync').css('top','30px'); + } else { + $('#nav-sync').css('top','5px'); + } + expandNode(global_navtree_object, n, true, true); // <- we added this line + showRoot(); +} + + +$(document).ready(function() { + + generate_autotoc(); + + (function (){ // wait until the first "selected" element has been created + try { + + // this line will triger an exception if there is no #selected element, i.e., before the tree structure is complete. + document.getElementById("selected").className = "item selected"; + + // ok, the default tree has been created, we can keep going... + + // expand the "Chapters" node + if(window.location.href.indexOf('unsupported')==-1) + expandNode(global_navtree_object, global_navtree_object.node.children[0].children[2], true, true); + else + expandNode(global_navtree_object, global_navtree_object.node.children[0].children[1], true, true); + + // Hide the root node "HDF5" + $(document.getElementsByClassName('index.html')[0]).parent().parent().css({display:"none"}); + + } catch (err) { + setTimeout(arguments.callee, 10); + } + })(); + + $(window).on("load", resizeHeight); +}); diff --git a/doxygen/hdf5doxy.css b/doxygen/hdf5doxy.css new file mode 100644 index 0000000..8c03860 --- /dev/null +++ b/doxygen/hdf5doxy.css @@ -0,0 +1,251 @@ + +/******** HDF5 specific CSS code ************/ + +/**** Styles removing elements ****/ + +/* remove the "modules|classes" link for module pages (they are already in the TOC) */ +div.summary { + display:none; +} + +/* remove */ +div.contents hr { + display:none; +} + +/**** ****/ + +p, dl.warning, dl.attention, dl.note +{ + max-width:60em; + text-align:justify; +} + +li { + max-width:55em; + text-align:justify; +} + +img { + border: 0; +} + +div.fragment { + display:table; /* this allows the element to be larger than its parent */ + padding: 0pt; +} +pre.fragment { + border: 1px solid #cccccc; + + margin: 2px 0px 2px 0px; + padding: 3px 5px 3px 5px; +} + +/* Common style for all HDF5's tables */ + +table.example, table.manual, table.manual-vl, table.manual-hl { + max-width:100%; + border-collapse: collapse; + border-style: solid; + border-width: 1px; + border-color: #cccccc; + font-size: 1em; + + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + -moz-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); +} + +table.example th, table.manual th, table.manual-vl th, table.manual-hl th { + padding: 0.5em 0.5em 0.5em 0.5em; + text-align: left; + padding-right: 1em; + color: #555555; + background-color: #F4F4E5; + + background-image: -webkit-gradient(linear,center top,center bottom,from(#FFFFFF), color-stop(0.3,#FFFFFF), color-stop(0.30,#FFFFFF), color-stop(0.98,#F4F4E5), to(#ECECDE)); + background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 30%, #F4F4E5 98%, #ECECDE); + filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#FFFFFF', endColorstr='#F4F4E5'); +} + +table.example td, table.manual td, table.manual-vl td, table.manual-hl td { + vertical-align:top; + border-width: 1px; + border-color: #cccccc; +} + +/* header of headers */ +table th.meta { + text-align:center; + font-size: 1.2em; + background-color:#FFFFFF; +} + +/* intermediate header */ +table th.inter { + text-align:left; + background-color:#FFFFFF; + background-image:none; + border-style:solid solid solid solid; + border-width: 1px; + border-color: #cccccc; +} + +/** class for example / output tables **/ + +table.example { +} + +table.example th { +} + +table.example td { + padding: 0.5em 0.5em 0.5em 0.5em; + vertical-align:top; +} + +/* standard class for the manual */ + +table.manual, table.manual-vl, table.manual-hl { + padding: 0.2em 0em 0.5em 0em; +} + +table.manual th, table.manual-vl th, table.manual-hl th { + margin: 0em 0em 0.3em 0em; +} + +table.manual td, table.manual-vl td, table.manual-hl td { + padding: 0.3em 0.5em 0.3em 0.5em; + vertical-align:top; + border-width: 1px; +} + +table.manual td.alt, table.manual tr.alt, table.manual-vl td.alt, table.manual-vl tr.alt { + background-color: #F4F4E5; +} + +table.manual-vl th, table.manual-vl td, table.manual-vl td.alt { + border-color: #cccccc; + border-width: 1px; + border-style: none solid none solid; +} + +table.manual-vl th.inter { + border-style: solid solid solid solid; +} + +table.manual-hl td { + border-color: #cccccc; + border-width: 1px; + border-style: solid none solid none; +} + +table td.code { + font-family: monospace; +} + +h2 { + margin-top:2em; + border-style: none none solid none; + border-width: 1px; + border-color: #cccccc; +} + +/**** Table of content in the side-nav ****/ + + +div.toc { + margin:0; + padding: 0.3em 0 0 0; + width:100%; + float:none; + position:absolute; + bottom:0; + border-radius:0px; + border-style: solid none none none; + max-height:50%; + overflow-y: scroll; +} + +div.toc h3 { + margin-left: 0.5em; + margin-bottom: 0.2em; +} + +div.toc ul { + margin: 0.2em 0 0.4em 0.5em; +} + +span.cpp11,span.cpp14,span.cpp17 { + color: #119911; + font-weight: bold; +} + +.newin3x { + color: #a37c1a; + font-weight: bold; +} + +div.warningbox { + max-width:60em; + border-style: solid solid solid solid; + border-color: red; + border-width: 3px; +} + +/**** old HDF5's styles ****/ + + +table.tutorial_code td { + border-color: transparent; /* required for Firefox */ + padding: 3pt 5pt 3pt 5pt; + vertical-align: top; +} + + +/* Whenever doxygen meets a '\n' or a '<BR/>', it will put + * the text containing the character into a <p class="starttd">. + * This little hack together with table.tutorial_code td.note + * aims at fixing this issue. */ +table.tutorial_code td.note p.starttd { + margin: 0px; + border: none; + padding: 0px; +} + +div.eimainmenu { + text-align: center; +} + +/* center version number on main page */ +h3.version { + text-align: center; +} + + +td.width20em p.endtd { + width: 20em; +} + +/* needed for huge screens */ +.ui-resizable-e { + background-repeat: repeat-y; +} + +/* Style external links -- nav-tree is different */ + +#nav-tree .label a { + padding:2px 16px 2px 2px; +} + +a { + outline: none; + text-decoration: none; + padding: 2px 1px 0; +} + +a[href*="http"] { + background: url('https://mdn.mozillademos.org/files/12982/external-link-52.png') no-repeat 100% 0; + background-size: 12px 12px; + padding-right: 16px; +} diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml new file mode 100644 index 0000000..7f71c24 --- /dev/null +++ b/doxygen/hdf5doxy_layout.xml @@ -0,0 +1,182 @@ +<?xml version="1.0"?> +<doxygenlayout version="1.0"> + <!-- Navigation index tabs for HTML output --> + <navindex> + <tab type="user" url="index.html" title="Overview" /> + <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/Learning+HDF5" title="Getting started" /> + <tab type="user" url="@ref Cookbook" title="Cookbook" /> + <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" /> + <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" /> + <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary" title="Glossary" /> + <tab type="user" url="@ref RM" title="Reference Manual" /> + <tab type="user" url="@ref TN" title="Technical Notes" /> + <tab type="user" url="@ref SPEC" title="Specifications" /> + <tab type="user" url="@ref About" title="About" /> + </navindex> + + <!-- Layout definition for a class page --> + <class> + <briefdescription visible="no"/> + <includes visible="$SHOW_INCLUDE_FILES"/> + <detaileddescription title=""/> + <inheritancegraph visible="$CLASS_GRAPH"/> + <collaborationgraph visible="$COLLABORATION_GRAPH"/> + <allmemberslink visible="yes"/> + <memberdecl> + <nestedclasses visible="yes" title=""/> + <publictypes title=""/> + <publicslots title=""/> + <signals title=""/> + <publicmethods title=""/> + <publicstaticmethods title=""/> + <publicattributes title=""/> + <publicstaticattributes title=""/> + <protectedtypes title=""/> + <protectedslots title=""/> + <protectedmethods title=""/> + <protectedstaticmethods title=""/> + <protectedattributes title=""/> + <protectedstaticattributes title=""/> + <packagetypes title=""/> + <packagemethods title=""/> + <packagestaticmethods title=""/> + <packageattributes title=""/> + <packagestaticattributes title=""/> + <properties title=""/> + <events title=""/> + <privatetypes title=""/> + <privateslots title=""/> + <privatemethods title=""/> + <privatestaticmethods title=""/> + <privateattributes title=""/> + <privatestaticattributes title=""/> + <friends title=""/> + <related title="" subtitle=""/> + <membergroups visible="yes"/> + </memberdecl> + + <memberdef> + <inlineclasses title=""/> + <typedefs title=""/> + <enums title=""/> + <constructors title=""/> + <functions title=""/> + <related title=""/> + <variables title=""/> + <properties title=""/> + <events title=""/> + </memberdef> + <usedfiles visible="$SHOW_USED_FILES"/> + <authorsection visible="yes"/> + </class> + + <!-- Layout definition for a namespace page --> + <namespace> + <briefdescription visible="yes"/> + <memberdecl> + <nestednamespaces visible="yes" title=""/> + <classes visible="yes" title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <inlineclasses title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + </memberdef> + <authorsection visible="yes"/> + </namespace> + + <!-- Layout definition for a file page --> + <file> + <briefdescription visible="yes"/> + <includes visible="$SHOW_INCLUDE_FILES"/> + <includegraph visible="$INCLUDE_GRAPH"/> + <includedbygraph visible="$INCLUDED_BY_GRAPH"/> + <sourcelink visible="yes"/> + <memberdecl> + <classes visible="yes" title=""/> + <namespaces visible="yes" title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <inlineclasses title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + </memberdef> + <authorsection/> + </file> + + <!-- Layout definition for a group page --> + <group> + <briefdescription visible="no"/> + <detaileddescription title=""/> + <groupgraph visible="$GROUP_GRAPHS"/> + <memberdecl> + <nestedgroups visible="yes" title=""/> + <dirs visible="yes" title=""/> + <files visible="yes" title=""/> + <namespaces visible="yes" title=""/> + <classes visible="yes" title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <enumvalues title=""/> + <functions title=""/> + <variables title=""/> + <signals title=""/> + <publicslots title=""/> + <protectedslots title=""/> + <privateslots title=""/> + <events title=""/> + <properties title=""/> + <friends title=""/> + <membergroups visible="yes"/> + </memberdecl> + + <memberdef> + <pagedocs/> + <inlineclasses title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <enumvalues title=""/> + <functions title=""/> + <variables title=""/> + <signals title=""/> + <publicslots title=""/> + <protectedslots title=""/> + <privateslots title=""/> + <events title=""/> + <properties title=""/> + <friends title=""/> + </memberdef> + <authorsection visible="yes"/> + </group> + + <!-- Layout definition for a directory page --> + <directory> + <briefdescription visible="yes"/> + <directorygraph visible="yes"/> + <memberdecl> + <dirs visible="yes"/> + <files visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + </directory> +</doxygenlayout> diff --git a/doxygen/img/FF-IH_FileGroup.gif b/doxygen/img/FF-IH_FileGroup.gif Binary files differnew file mode 100644 index 0000000..b0d76f5 --- /dev/null +++ b/doxygen/img/FF-IH_FileGroup.gif diff --git a/doxygen/img/FF-IH_FileObject.gif b/doxygen/img/FF-IH_FileObject.gif Binary files differnew file mode 100644 index 0000000..8eba623 --- /dev/null +++ b/doxygen/img/FF-IH_FileObject.gif diff --git a/doxygen/img/FileFormatSpecChunkDiagram.jpg b/doxygen/img/FileFormatSpecChunkDiagram.jpg Binary files differnew file mode 100644 index 0000000..03fd90a --- /dev/null +++ b/doxygen/img/FileFormatSpecChunkDiagram.jpg diff --git a/doxygen/img/HDFG-logo.png b/doxygen/img/HDFG-logo.png Binary files differindex a2d52a9..38300ff 100644 --- a/doxygen/img/HDFG-logo.png +++ b/doxygen/img/HDFG-logo.png diff --git a/doxygen/img/PaletteExample1.gif b/doxygen/img/PaletteExample1.gif Binary files differnew file mode 100644 index 0000000..8694d9d --- /dev/null +++ b/doxygen/img/PaletteExample1.gif diff --git a/doxygen/img/Palettes.fm.anc.gif b/doxygen/img/Palettes.fm.anc.gif Binary files differnew file mode 100644 index 0000000..d344c03 --- /dev/null +++ b/doxygen/img/Palettes.fm.anc.gif diff --git a/doxygen/img/ftv2node.png b/doxygen/img/ftv2node.png Binary files differnew file mode 100644 index 0000000..63c605b --- /dev/null +++ b/doxygen/img/ftv2node.png diff --git a/doxygen/img/ftv2pnode.png b/doxygen/img/ftv2pnode.png Binary files differnew file mode 100644 index 0000000..c6ee22f --- /dev/null +++ b/doxygen/img/ftv2pnode.png diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index 90b3418..a7d30ec 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -439,62 +439,288 @@ extern "C" { #define H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0 #define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED 1 +/** + * H5AC_cache_config_t is a public structure intended for use in public APIs. + * At least in its initial incarnation, it is basically a copy of \c struct + * \c H5C_auto_size_ctl_t, minus the \c report_fcn field, and plus the + * \c dirty_bytes_threshold field. + * + * The \c report_fcn field is omitted, as including it would require us to make + * \c H5C_t structure public. + * + * The \c dirty_bytes_threshold field does not appear in \c H5C_auto_size_ctl_t, + * as synchronization between caches on different processes is handled at the \c + * H5AC level, not at the level of \c H5C. Note however that there is + * considerable interaction between this value and the other fields in this + * structure. + * + * Similarly, the \c open_trace_file, \c close_trace_file, and \c + * trace_file_name fields do not appear in \c H5C_auto_size_ctl_t, as most trace + * file issues are handled at the \c H5AC level. The one exception is storage + * of the pointer to the trace file, which is handled by \c H5C. + * + * The structure is in H5ACpublic.h as we may wish to allow different + * configuration options for metadata and raw data caches. + */ + +//! <!-- [H5AC_cache_config_t_snip] --> typedef struct H5AC_cache_config_t { /* general configuration fields: */ + //! <!-- [H5AC_cache_config_t_general_snip] --> int version; + /**< Integer field indicating the the version of the H5AC_cache_config_t + * in use. This field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION + * (defined in H5ACpublic.h). */ hbool_t rpt_fcn_enabled; + /**< Boolean flag indicating whether the adaptive cache resize report + * function is enabled. This field should almost always be set to disabled + * (0). Since resize algorithm activity is reported via stdout, it MUST be + * set to disabled (0) on Windows machines.\n + * The report function is not supported code, and can be expected to change + * between versions of the library. Use it at your own risk. */ hbool_t open_trace_file; + /**< Boolean field indicating whether the + * \ref H5AC_cache_config_t.trace_file_name "trace_file_name" + * field should be used to open a trace file for the cache.\n + * The trace file is a debugging feature that allows the capture + * of top level metadata cache requests for purposes of debugging + * and/or optimization. This field should normally be set to 0, as + * trace file collection imposes considerable overhead.\n + * This field should only be set to 1 when the + * \ref H5AC_cache_config_t.trace_file_name "trace_file_name" + * contains the full path of the desired trace file, and either + * there is no open trace file on the cache, or the + * \ref H5AC_cache_config_t.close_trace_file "close_trace_file" + * field is also 1.\n + * The trace file feature is unsupported unless used at the + * direction of The HDF Group. It is intended to allow The HDF + * Group to collect a trace of cache activity in cases of occult + * failures and/or poor performance seen in the field, so as to aid + * in reproduction in the lab. If you use it absent the direction + * of The HDF Group, you are on your own. */ + hbool_t close_trace_file; - char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1]; + /**< Boolean field indicating whether the current trace file + *(if any) should be closed.\n + * See the above comments on the \ref H5AC_cache_config_t.open_trace_file + * "open_trace_file" field. This field should be set to 0 unless there is + * an open trace file on the cache that you wish to close.\n + * The trace file feature is unsupported unless used at the direction of + * The HDF Group. It is intended to allow The HDF Group to collect a trace + * of cache activity in cases of occult failures and/or poor performance + * seen in the field, so as to aid in reproduction in the lab. If you use + * it absent the direction of The HDF Group, you are on your own. */ + + char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1]; + /**< Full path of the trace file to be opened if the + * \ref H5AC_cache_config_t.open_trace_file "open_trace_file" field is set + * to 1.\n + * In the parallel case, an ascii representation of the MPI rank of the + * process will be appended to the file name to yield a unique trace file + * name for each process.\n + * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN + * characters.\n + * The trace file feature is unsupported unless used at the direction of + * The HDF Group. It is intended to allow The HDF Group to collect a trace + * of cache activity in cases of occult failures and/or poor performance + * seen in the field, so as to aid in reproduction in the lab. If you use + * it absent the direction of The HDF Group, you are on your own. */ hbool_t evictions_enabled; + /**< A boolean flag indicating whether evictions from the metadata cache + * are enabled. This flag is initially set to enabled (1).\n + * In rare circumstances, the raw data throughput quirements may be so high + * that the user wishes to postpone metadata writes so as to reserve I/O + * throughput for raw data. The \p evictions_enabled field exists to allow + * this. However, this is an extreme step, and you have no business doing + * it unless you have read the User Guide section on metadata caching, and + * have considered all other options carefully.\n + * The \p evictions_enabled field may not be set to disabled (0) + * unless all adaptive cache resizing code is disabled via the + * \ref H5AC_cache_config_t.incr_mode "incr_mode", + * \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode", + * \ref H5AC_cache_config_t.decr_mode "decr_mode" fields.\n + * When this flag is set to disabled (\c 0), the metadata cache will not + * attempt to evict entries to make space for new entries, and thus will + * grow without bound.\n + * Evictions will be re-enabled when this field is set back to \c 1. + * This should be done as soon as possible. */ hbool_t set_initial_size; - size_t initial_size; + /**< Boolean flag indicating whether the cache should be created + * with a user specified initial size. */ + + size_t initial_size; + /**< If \ref H5AC_cache_config_t.set_initial_size "set_initial_size" + * is set to 1, \p initial_size must contain he desired initial size in + * bytes. This value must lie in the closed interval + * [ \p min_size, \p max_size ]. (see below) */ double min_clean_fraction; + /**< This field specifies the minimum fraction of the cache + * that must be kept either clean or empty.\n + * 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> + * for details. */ size_t max_size; + /**< Upper bound (in bytes) on the range of values that the + * adaptive cache resize code can select as the maximum cache size. */ + size_t min_size; + /**< Lower bound (in bytes) on the range of values that the + * adaptive cache resize code can select as the mininum cache * size. */ long int epoch_length; + /**< Number of cache accesses between runs of the adaptive cache resize + * code. 50,000 is a good starting number. */ + //! <!-- [H5AC_cache_config_t_general_snip] --> /* size increase control fields: */ + //! <!-- [H5AC_cache_config_t_incr_snip] --> enum H5C_cache_incr_mode incr_mode; + /**< Enumerated value indicating the operational mode of the automatic + * cache size increase code. At present, only two values listed in + * #H5C_cache_incr_mode are legal. */ double lower_hr_threshold; + /**< Hit rate threshold used by the hit rate threshold cache size + * increment algorithm.\n + * When the hit rate over an epoch is below this threshold and the cache + * is full, the maximum size of the cache is multiplied by increment + * (below), and then clipped as necessary to stay within \p max_size, and + * possibly \p max_increment.\n + * This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good + * place to start. */ double increment; + /**< Factor by which the hit rate threshold cache size increment + * algorithm multiplies the current cache max size to obtain a tentative + * new cache size.\n + * The actual cache size increase will be clipped to satisfy the \p max_size + * specified in the general configuration, and possibly max_increment + * below.\n + * The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable + * value.\n + * If you set it to 1.0, you will effectively disable cache size increases. + */ hbool_t apply_max_increment; - size_t max_increment; + /**< Boolean flag indicating whether an upper limit should be applied to + * the size of cache size increases. */ + + size_t max_increment; + /**< Maximum number of bytes by which cache size can be increased in a + * single step -- if applicable. */ enum H5C_cache_flash_incr_mode flash_incr_mode; - double flash_multiple; - double flash_threshold; + /**< Enumerated value indicating the operational mode of the flash cache + * size increase code. At present, only two listed values in + * #H5C_cache_flash_incr_mode are legal.*/ + + double flash_multiple; + /**< The factor by which the size of the triggering entry / entry size + * increase is multiplied to obtain the initial cache size increment. This + * increment may be reduced to reflect existing free space in the cache and + * the \p max_size field above.\n + * The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good + * place to start.\n + * At present, this field must lie in the range [0.1, 10.0]. */ + + double flash_threshold; + /**< The factor by which the current maximum cache size is multiplied to + * obtain the minimum size entry / entry size increase which may trigger a + * flash cache size increase. \n + * At present, this value must lie in the range [0.1, 1.0]. */ + //! <!-- [H5AC_cache_config_t_incr_snip] --> /* size decrease control fields: */ + //! <!-- [H5AC_cache_config_t_decr_snip] --> enum H5C_cache_decr_mode decr_mode; + /**< Enumerated value indicating the operational mode of the tomatic + * cache size decrease code. At present, the values listed in + * #H5C_cache_decr_mode are legal.*/ double upper_hr_threshold; + /**< Hit rate threshold for the hit rate threshold and ageout with hit + * rate threshold cache size decrement algorithms.\n + * When \p decr_mode is #H5C_decr__threshold, and the hit rate over a given + * epoch exceeds the supplied threshold, the current maximum cache + * size is multiplied by decrement to obtain a tentative new (and smaller) + * maximum cache size.\n + * When \p decr_mode is #H5C_decr__age_out_with_threshold, there is + * no attempt to find and evict aged out entries unless the hit rate in + * the previous epoch exceeded the supplied threshold.\n + * This field must lie in the interval [0.0, 1.0].\n + * For #H5C_incr__threshold, .9995 or .99995 is a good place to start.\n + * For #H5C_decr__age_out_with_threshold, .999 might be more useful.*/ double decrement; + /**< In the hit rate threshold cache size decrease algorithm, this + * parameter contains the factor by which the current max cache size is + * multiplied to produce a tentative new cache size.\n + * The actual cache size decrease will be clipped to satisfy the + * \ref H5AC_cache_config_t.min_size "min_size" specified in the general + * configuration, and possibly \ref H5AC_cache_config_t.max_decrement + * "max_decrement".\n + * The parameter must be be in the interval [0.0, 1.0].\n + * If you set it to 1.0, you will effectively + * disable cache size decreases. 0.9 is a reasonable starting point. */ hbool_t apply_max_decrement; - size_t max_decrement; + /**< Boolean flag indicating ether an upper limit should be applied to + * the size of cache size decreases. */ + + size_t max_decrement; + /**< Maximum number of bytes by which the maximum cache size can be + * decreased in any single step -- if applicable.*/ int epochs_before_eviction; + /**< In the ageout based cache size reduction algorithms, this field + * contains the minimum number of epochs an entry must remain unaccessed in + * cache before the cache size reduction algorithm tries to evict it. 3 is a + * reasonable value. */ hbool_t apply_empty_reserve; - double empty_reserve; + /**< Boolean flag indicating whether the ageout based decrement + * algorithms will maintain a empty reserve when decreasing cache size. */ + + double empty_reserve; + /**< Empty reserve as a fraction maximum cache size if applicable.\n When + * so directed, the ageout based algorithms will not decrease the maximum + * cache size unless the empty reserve can be met.\n The parameter must lie + * in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. */ + //! <!-- [H5AC_cache_config_t_decr_snip] --> /* parallel configuration fields: */ + //! <!-- [H5AC_cache_config_t_parallel_snip] --> int dirty_bytes_threshold; - int metadata_write_strategy; + /**< Threshold number of bytes of dirty metadata generation for + * triggering synchronizations of the metadata caches serving the target + * file in the parallel case.\n Synchronization occurs whenever the number + * of bytes of dirty metadata created since the last synchronization exceeds + * this limit.\n This field only applies to the parallel case. While it is + * ignored elsewhere, it can still draw a value out of bounds error.\n It + * must be consistant across all caches on any given file.\n By default, + * this field is set to 256 KB. It shouldn't be more than half the current + * max cache size times the min clean fraction. */ + int metadata_write_strategy; + /**< Desired metadata write strategy. The valid values for this field + * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only + * process zero is allowed to write dirty metadata to disk.\n + * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero + * still makes the decisions as to what entries should be flushed, but the + * actual flushes are distributed across the processes in the computation to + * the extent possible.\n The src/H5ACpublic.h include file in the HDF5 + * library has detailed information on each strategy. */ + //! <!-- [H5AC_cache_config_t_parallel_snip] --> } H5AC_cache_config_t; +//! <!-- [H5AC_cache_config_t_snip] --> #ifdef __cplusplus } diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 28a0e85..0198668 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -22,17 +22,40 @@ #include "H5Opublic.h" /* Object Headers */ #include "H5Tpublic.h" /* Datatypes */ -/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */ +//! <!-- [H5A_info_t_snip] --> +/** + * Information struct for H5Aget_info() / H5Aget_info_by_idx() + */ typedef struct { - hbool_t corder_valid; /* Indicate if creation order is valid */ - H5O_msg_crt_idx_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of attribute name */ - hsize_t data_size; /* Size of raw data */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + H5O_msg_crt_idx_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of attribute name */ + hsize_t data_size; /**< Size of raw data */ } H5A_info_t; +//! <!-- [H5A_info_t_snip] --> -/* Typedef for H5Aiterate2() callbacks */ +//! <!-- [H5A_operator2_t_snip] --> +/** + * Typedef for H5Aiterate2() / H5Aiterate_by_name() callbacks + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in] ainfo The attribute’s info struct + * \param[in,out] op_data A pointer to the operator data passed in to + * H5Aiterate2() or H5Aiterate_by_name() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/); +//! <!-- [H5A_operator2_t_snip] --> /********************/ /* Public Variables */ @@ -45,45 +68,946 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam extern "C" { #endif -H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, - hid_t aapl_id); -H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, - hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id); -H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); -H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, - hid_t lapl_id); -H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, hid_t aapl_id, hid_t lapl_id); -H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); -H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); -H5_DLL herr_t H5Aclose(hid_t attr_id); -H5_DLL hid_t H5Aget_space(hid_t attr_id); -H5_DLL hid_t H5Aget_type(hid_t attr_id); -H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Closes the specified attribute + * + * \attr_id + * + * \return \herr_t + * + * \details H5Aclose() terminates access to the attribute specified by + * \p attr_id by releasing the identifier. + * + * \attention Further use of a released attribute identifier is illegal; a + * function using such an identifier will generate an error. + * + * \since 1.0.0 + * + * \see H5Acreate(), H5Aopen() + */ +H5_DLL herr_t H5Aclose(hid_t attr_id); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] attr_name Name of attribute + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate2() creates an attribute, \p attr_name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The access property list is currently unused, but will be used in + * the future. This property list should currently be #H5P_DEFAULT. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT. + * + * \note If \p loc_id is a file identifier, the attribute will be attached + * that file’s root group. + * + * \since 1.8.0 + * + * \see H5Aclose() + * + */ +H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, + hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] obj_name Name, relative to \p loc_id, of object that + * attribute is to be attached to + * \param[in] attr_name Attribute name + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is + * attached to the object specified by \p loc_id and \p obj_name. + * + * \p loc_id is a location identifier; \p obj_name is the object + * name relative to \p loc_id. If \p loc_id fully specifies the + * object to which the attribute is to be attached, \p obj_name + * should be '.' (a dot). + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and + * dataspace, \p type_id and \p space_id, which are created with + * the H5T and H5S interfaces respectively. + * + * The attribute creation and access property lists are currently + * unused, but will be used in the future for optional attribute + * creation and access properties. These property lists should + * currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * The attribute identifier returned by this function must be + * released with H5close() or resource leaks will develop. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, + hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Deletes an attribute from a specified location + * + * \fgdt_loc_id + * \param[in] attr_name Name of the attribute to delete + * + * \return \herr_t + * + * \details H5Adelete() removes the attribute specified by its name, + * \p attr_name, from a file, dataset, group, or named datatype. + * This function should not be used when attribute identifiers + * are open on \p loc_id as it may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Deletes an attribute from an object according to index order + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, from which + * attribute is to be removed + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in] n Offset within index + * \lapl_id + * + * \return \herr_t + * + * \details H5Adelete_by_idx() removes an attribute, specified by its + * location in an index, from an object. + * + * The object from which the attribute is to be removed is + * specified by a location identifier and name, \p loc_id and + * \p obj_name, respectively. If \p loc_id fully specifies the + * object from which the attribute is to be removed, \p obj_name + * should be '.' (a dot). + * + * The attribute to be removed is specified by a position in an + * index, \p n. The type of index is specified by \p idx_type and + * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or + * #H5_INDEX_CRT_ORDER, for an index by creation order. The order + * in which the index is to be traversed is specified by \p order + * and may be #H5_ITER_INC (increment) for top-down iteration, + * #H5_ITER_DEC (decrement) for bottom-up iteration, or + * #H5_ITER_NATIVE, in which case HDF5 will iterate in the + * fastest-available order. For example, if \p idx_type, \p order, + * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5, + * respectively, the fifth attribute by alpha-numeric order of + * attribute names will be removed. + * + * For a discussion of \p idx_type and \p order, the valid values + * of those parameters, and the use of \p n, see the description + * of H5Aiterate2(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, + hsize_t n, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Removes an attribute from a specified location + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, from which + * attribute is to be removed + * \param[in] attr_name Name of attribute to delete + * \lapl_id + * + * \return \herr_t + * + * \details H5Adelete_by_name() removes the attribute \p attr_name + * from an object specified by location and name, \p loc_id and + * \p obj_name, respectively. + * + * If \p loc_id fully specifies the object from which the + * attribute is to be removed, \p obj_name should be '.' (a dot). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines whether an attribute with a given name exists on an + * object + * + * \fgdt_loc_id{obj_id} + * \param[in] attr_name Attribute name + * + * \return \htri_t + * + * \details H5Aexists() determines whether the attribute \p attr_name + * exists on the object specified by \p obj_id. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines whether an attribute with a given name exists on an + * object + * + * \fgdt_loc_id{obj_id} + * \param[in] obj_name Object name + * \param[in] attr_name Attribute name + * \lapl_id + * + * \return \htri_t + * + * \details H5Aexists_by_name() determines whether the attribute + * \p attr_name exists on an object. That object is specified by + * its location and name, \p loc_id and \p obj_name, respectively. + * + * \p loc_id specifies a location in the file containing the object. + * \p obj_name is the name of the object to which the attribute is + * attached and can be a relative name, relative to \p loc_id, + * or an absolute name, based in the root group of the file. If + * \p loc_id fully specifies the object, \p obj_name should be '.' + * (a dot). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute creation property list identifier + * + * \attr_id + * + * \return \hid_tv{attribute's creation property list} + * + * \details H5Aget_create_plist() returns an identifier for the attribute + * creation property list associated with the attribute specified + * by \p attr_id. + * + * The creation property list identifier should be released with + * H5Pclose(). + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information, by attribute identifier + * + * \attr_id + * \param[out] ainfo Attribute information struct + * + * \return \herr_t + * + * \details H5Aget_info() retrieves attribute information, locating the + * attribute with an attribute identifier, \p attr_id, which is + * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The + * attribute information is returned in the \p ainfo struct. + * + * The \p ainfo struct is defined as follows: + * \snippet this H5A_info_t_snip + * + * \p corder_valid indicates whether the creation order data is + * valid for this attribute. Note that if creation order is not + * being tracked, no creation order data will be valid. Valid + * values are \c TRUE and \c FALSE. + * + * \p corder is a positive integer containing the creation + * order of the attribute. This value is 0-based, so, for + * example, the third attribute created will have a \p corder + * value of 2. + * + * \p cset indicates the character set used for the attribute’s + * name; valid values are defined in H5Tpublic.h and include + * the following: + * \csets + * This value is set with H5Pset_char_encoding(). + * + * \p data_size indicates the size, in the number of characters, + * of the attribute. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information by attribute index position + * + * \fgdt_loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] idx_type Type of index + * \param[in] order Index traversal order + * \param[in] n Attribute’s position in index + * \param[out] ainfo Struct containing returned attribute information + * \lapl_id + * + * \return \herr_t + * + * \details H5Aget_info_by_idx() retrieves information for an attribute + * that is attached to an object, which is specified by its + * location and name, \p loc_id and \p obj_name, respectively. + * The attribute is located by its index position and the attribute + * information is returned in the \p ainfo struct. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The attribute is located by means of an index type, an index + * traversal order, and a position in the index, \p idx_type, + * \p order and \p n, respectively. These parameters and their + * valid values are discussed in the description of H5Aiterate2(). + * + * The \p ainfo struct, which will contain the returned attribute + * information, is described in H5Aget_info(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo /*out*/, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information, by attribute name + * + * \fgdt_loc_id + * + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] attr_name Attribute name + * \param[out] ainfo Struct containing returned attribute information + * \lapl_id + * + * \return \herr_t + * + * \details H5Aget_info_by_name() retrieves information for an attribute, + * \p attr_name, that is attached to an object specified by its + * location and name, \p loc_id and \p obj_name, respectively. + * The attribute information is returned in the \p ainfo struct. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The \p ainfo struct is described in H5Aget_info(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, + H5A_info_t *ainfo /*out*/, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute name + * + * \attr_id + * \param[in] buf_size The size of the buffer to store the name in + * \param[out] buf Buffer to store name in + * + * \return Returns the length of the attribute's name, which may be longer + * than \p buf_size, if successful. Otherwise returns a negative + * value. + * + * \details H5Aget_name() retrieves the name of an attribute specified by + * the identifier, \p attr_id. Up to \p buf_size characters are + * stored in \p buf followed by a \0 string terminator. If the + * name of the attribute is longer than (\p buf_size -1), the + * string terminator is stored in the last position of the buffer + * to properly terminate the string. + * + * If the user only wants to find out the size of this name, the + * values 0 and NULL can be passed in for the parameters + * \p bufsize and \p buf. + * + * \since 1.0.0 + * + */ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute name, by attribute index position + * + * \fgdt_loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] idx_type Type of index + * \param[in] order Index traversal order + * \param[in] n Attribute’s position in index + * \param[out] name Attribute name + * \param[in] size Size, in bytes, of attribute name + * \lapl_id + * + * \return Returns attribute name size, in bytes, if successful; + * otherwise returns a negative value. + * + * \details H5Aget_name_by_idx() retrieves the name of an attribute that is + * attached to an object, which is specified by its location and + * name, \p loc_id and \p obj_name, respectively. The attribute is + * located by its index position, the size of the name is specified + * in \p size, and the attribute name is returned in \p name. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The attribute is located by means of an index type, an index + * traversal order, and a position in the index, \p idx_type, + * \p order and \p n, respectively. These parameters and their + * valid values are discussed in the description of H5Aiterate2(). + * + * If the attribute name’s size is unknown, the values 0 and NULL + * can be passed in for the parameters \p size and \p name. The + * function’s return value will provide the correct value for + * \p size. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets a copy of the dataspace for an attribute + * + * \attr_id + * + * \return \hid_tv{attribute dataspace} + * + * \details H5Aget_space() retrieves a copy of the dataspace for an + * attribute. The dataspace identifier returned from this + * function must be released with H5Sclose() or resource leaks + * will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aget_space(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Returns the amount of storage required for an attribute + * + * \attr_id + * + * \return Returns the amount of storage size allocated for the attribute; + * otherwise returns 0 (zero). + * + * \details H5Aget_storage_size() returns the amount of storage that is + * required for the specified attribute, \p attr_id. + * + * \since 1.6.0 + * + */ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); -H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); -H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, - H5A_info_t *ainfo /*out*/, hid_t lapl_id); -H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo /*out*/, hid_t lapl_id); -H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); -H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name, - const char *new_attr_name, hid_t lapl_id); -H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, - H5A_operator2_t op, void *op_data); -H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, - hid_t lapd_id); -H5_DLL herr_t H5Adelete(hid_t loc_id, const char *name); -H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id); -H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, hid_t lapl_id); -H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); -H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute datatype + * + * \attr_id + * + * \return \hid_t{datatype} + * + * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * The datatype is reopened if it is a named type before returning + * it to the application. The datatypes returned by this function + * are always read-only. If an error occurs when atomizing the + * return datatype, then the datatype is closed. + * + * The datatype identifier returned from this function must be + * released with H5Tclose() or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aget_type(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls user-defined function for each attribute on an object + * + * \fgdt_loc_id + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in,out] idx Initial and returned offset within index + * \param[in] op User-defined function to pass each attribute to + * \param[in,out] op_data User data to pass through to and to be returned + * by iterator operator function + * + * \return \herr_t + * Further note that this function returns the return value of the + * last operator if it was non-zero, which can be a negative value, + * zero if all attributes were processed, or a positive value + * indicating short-circuit success. + * + * \details H5Aiterate2() iterates over the attributes attached to a + * dataset, named datatype, or group, as specified by \p loc_id. + * For each attribute, user-provided data, \p op_data, with + * additional information as defined below, is passed to a + * user-defined function, \p op, which operates on that + * attribute. + * + * The order of the iteration and the attributes iterated over + * are specified by three parameters: the index type, + * \p idx_type; the order in which the index is to be traversed, + * \p order; and the attribute’s position in the index, \p idx. + * + * The type of index specified by \p idx_type can be one of the + * following: + * + * \indexes + * + * The order in which the index is to be traversed, as specified + * by \p order, can be one of the following: + * + * \orders + * + * The next attribute to be operated on is specified by \p idx, + * a position in the index. + * + * For example, if \p idx_type, \p order, and \p idx are set to + * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute + * in question is the fifth attribute from the beginning of the + * alpha-numeric index of attribute names. If \p order were set to + * #H5_ITER_DEC, it would be the fifth attribute from the end of + * the index. + * + * The parameter \p idx is passed in on an H5Aiterate2() call with + * one value and may be returned with another value. The value + * passed in identifies the parameter to be operated on first; + * the value returned identifies the parameter to be operated on + * in the next step of the iteration. + * + * \p op is a user-defined function whose prototype is defined + * as follows: + * \snippet this H5A_operator2_t_snip + * \click4more + * + * \note This function is also available through the H5Aiterate() macro. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, + H5A_operator2_t op, void *op_data); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls user-defined function for each attribute on an object + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in,out] idx Initial and returned offset within index + * \param[in] op User-defined function to pass each attribute to + * \param[in,out] op_data User data to pass through to and to be returned + * by iterator operator function + * \lapl_id + * + * \return \herr_t + * Further note that this function returns the return value of + * the last operator if it was non-zero, which can be a negative + * value, zero if all attributes were processed, or a positive value + * indicating short-circuit success. + * + * \details H5Aiterate_by_name() iterates over the attributes attached + * to the dataset or group specified with \p loc_id and \p obj_name. + * For each attribute, user-provided data, \p op_data, with + * additional information as defined below, is passed to a + * user-defined function, \p op, which operates on that attribute. + * + * If \p loc_id fully specifies the object to which these + * attributes are attached, \p obj_name should be '.' (a dot). + * + * The order of the iteration and the attributes iterated over + * are specified by three parameters: the index type, \p idx_type; + * the order in which the index is to be traversed, \p order; + * and the attribute’s position in the index, \p idx. + * + * The type of index specified by \p idx_type can be one of the + * following: + * + * \indexes + * + * The order in which the index is to be traversed, as specified + * by \p order, can be one of the following: + * + * \orders + * + * The next attribute to be operated on is specified by \p idx, + * a position in the index. + * + * For example, if \p idx_type, \p order, and \p idx are set to + * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute + * in question is the fifth attribute from the beginning of the + * alpha-numeric index of attribute names. If \p order were set to + * #H5_ITER_DEC, it would be the fifth attribute from the end of + * the index. + * + * The parameter \p idx is passed in on an H5Aiterate_by_name() + * call with one value and may be returned with another value. The + * value passed in identifies the parameter to be operated on first; + * the value returned identifies the parameter to be operated on in + * the next step of the iteration. + * + * \p op is a user-defined function whose prototype is defined + * as follows: + * \snippet this H5A_operator2_t_snip + * \click4more + * + * Valid return values from an operator and the resulting + * H5Aiterate_by_name() and \p op behavior are as follows: + * + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li A positive value causes the iterator to immediately return + * that positive value, indicating short-circuit success. + * The iterator can be restarted at the next attribute, as + * indicated by the return value of \p idx. + * \li A negative value causes the iterator to immediately return + * that value, indicating failure. The iterator can be + * restarted at the next attribute, as indicated by the return + * value of \p idx. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, + hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object specified by object identifier and + * attribute name + * + * \fgdt_loc_id{obj_id} + * \param[in] attr_name Name of attribute to open + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen() opens an existing attribute, \p attr_name, that is + * attached to object specified by an object identifier, \p obj_id. + * + * The attribute access property list, \p aapl_id, is currently unused + * and should be #H5P_DEFAULT. + * + * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called + * before the attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + * \see H5Aclose(), H5Acreate() + */ +H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens the nth attribute attached to an object + * + * \loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] idx_type Type of index + * \param[in] order Index traversal order + * \param[in] n Attribute’s position in index + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_idx() opens an existing attribute that is attached + * to an object specified by location and name, \p loc_id and + * \p obj_name, respectively. If \p loc_id fully specifies the + * object to which the attribute is attached, \p obj_name, should + * be '.' (a dot). + * + * The attribute is identified by an index type, an index traversal + * order, and a position in the index, \p idx_type, \p order and + * \p n, respectively. These parameters and their valid values are + * discussed in the description of H5Aiterate2(). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_name() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, + hsize_t n, hid_t aapl_id, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object by object name and attribute name + * + * \fgdt_loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to \p loc_id + * \param[in] attr_name Name of attribute to open + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_name() opens an existing attribute, \p attr_name, + * that is attached to an object specified by location and name, + * \p loc_id and \p obj_name, respectively. + * + * \p loc_id specifies a location from which the target object can + * be located and \p obj_name is an object name relative to + * \p loc_id. If \p loc_id fully specifies the object to which the + * attribute is attached, \p obj_name should be '.' (a dot). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_idx() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, + hid_t lapl_id); +/*-------------------------------------------------------------------------- */ +/** + * \ingroup H5A + * + * \brief Reads the value of an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Buffer for data to be read + * + * \return \herr_t + * + * \details H5Aread() reads an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. The + * entire attribute is read into \p buf from the file. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 The \p dims parameter was added to the Fortran API in this + * release. + * \since 1.0.0 + * + * \see H5Awrite() + * + */ +H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Renames an attribute + * + * \fgdt_loc_id + * \param[in] old_name Name of the attribute to be changed + * \param[in] new_name New name for the attribute + * + * \return \herr_t + * + * \details H5Arename() changes the name of the attribute located at + * \p loc_id. + * + * The old name, \p old_name, is changed to the new name, + * \p new_name. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Writes data to an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Data to be written + * + * \return \herr_t + * + * \details H5Awrite() writes an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. + * The entire attribute is written from \p buf to the file. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the datatype. + * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for + * Fortran codes), which defaults to 1 character in size. + * See H5Tset_size() and Creating variable-length string datatypes. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 Fortran \p dims parameter added in this release + * \since 1.0.0 + * \see H5Aread() + * + */ +H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, whose + * attribute is to be renamed + * \param[in] old_attr_name Prior attribute name + * \param[in] new_attr_name New attribute name + * \lapl_id + * + * \details H5Arename_by_name() changes the name of attribute that is + * attached to the object specified by \p loc_id and \p obj_name. + * The attribute named \p old_attr_name is renamed + * \p new_attr_name. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name, + const char *new_attr_name, hid_t lapl_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -95,16 +1019,186 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char * /* Typedefs */ -/* Typedef for H5Aiterate1() callbacks */ +//! <!-- [H5A_operator1_t_snip] --> +/** + * \brief Typedef for H5Aiterate1() callbacks + * + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in,out] operator_data A pointer to the operator data passed in to + * H5Aiterate1() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, void *operator_data /*in,out*/); +//! <!-- [H5A_operator1_t_snip] --> /* Function prototypes */ -H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id); -H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name); -H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); -H5_DLL int H5Aget_num_attrs(hid_t loc_id); -H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] name Name of attribute to locate and open + * \param[in] type_id Identifier of attribute datatype + * \space_id + * \acpl_id + * + * \return \hid_tv{attribute} + * + * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * + * \deprecated Deprecated in favor of H5Acreate2() + * + * \details H5Acreate1() creates an attribute, \p name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \since 1.8.0 + * + * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and + * deprecated in this release. + * + * \see H5Aclose() + * + */ +H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines the number of attributes attached to an object + * + * \fgdt_loc_id + * + * \return Returns the number of attributes if successful; otherwise returns + * a negative value. + * + * \deprecated This function is deprecated in favor of the functions + * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx(). + * + * \details H5Aget_num_attrs() returns the number of attributes attached to + * the object specified by its identifier, \p loc_id. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Aget_num_attrs(hid_t loc_id); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls a user’s function for each attribute on an object + * + * \loc_id + * \param[in,out] idx Starting (in) and ending (out) attribute index + * \param[in] op User's function to pass each attribute to + * \param[in,out] op_data User's data to pass through to iterator operator + * function + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Aiterate2(). + * + * \details H5Aiterate1() iterates over the attributes of the object + * specified by its identifier, \p loc_id. The object can be a + * group, dataset, or named datatype. For each attribute of the + * object, the \p op_data and some additional information specified + * below are passed to the operator function \p op. The iteration + * begins with the attribute specified by its index, \p idx; the + * index for the next attribute to be processed by the operator, + * \p op, is returned in \p idx. If \p idx is the null pointer, + * then all attributes are processed. + * + * \p op is a user-defined function whose prototype is defined as follows: + * \snippet this H5A_operator1_t_snip + * \click4more + * + * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() + * and deprecated in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void *op_data); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens the attribute specified by its index + * + * \loc_id + * \param[in] idx Index of the attribute to open + * + * \return \hid_tv{attribute} + * + * \deprecated This function is deprecated in favor of the function + * H5Aopen_by_idx(). + * + * \details H5Aopen_idx() opens an attribute which is attached to the + * object specified with \p loc_id . The location object may be + * either a group, dataset, or named datatype, all of which may + * have any sort of attribute. The attribute specified by the index, + * \p idx , indicates the attribute to access. The value of \p idx + * is a 0-based, non-negative integer. The attribute identifier + * returned from this function must be released with H5Aclose() + * or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute specified by name + * + * \loc_id + * \param[in] name Attribute name + * + * \return \hid_tv{attribute} + * + * \deprecated This function is deprecated in favor of the function + * H5Aopen_by_name(). + * + * \details H5Aopen_name() opens an attribute specified by its name, + * \p name, which is attached to the object specified with + * \p loc_id. The location object may be either a group, dataset, + * or named datatype, which may have any sort of attribute. The + * attribute identifier returned from this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Cpublic.h b/src/H5Cpublic.h index 0e6fb84..79ece10 100644 --- a/src/H5Cpublic.h +++ b/src/H5Cpublic.h @@ -31,15 +31,34 @@ extern "C" { #endif -enum H5C_cache_incr_mode { H5C_incr__off, H5C_incr__threshold }; +enum H5C_cache_incr_mode { + H5C_incr__off, + /**<Automatic cache size increase is disabled, and the remaining increment fields are ignored.*/ -enum H5C_cache_flash_incr_mode { H5C_flash_incr__off, H5C_flash_incr__add_space }; + H5C_incr__threshold + /**<Automatic cache size increase is enabled using the hit rate threshold algorithm.*/ +}; + +enum H5C_cache_flash_incr_mode { + H5C_flash_incr__off, + /**<Flash cache size increase is disabled.*/ + + H5C_flash_incr__add_space + /**<Flash cache size increase is enabled using the add space algorithm.*/ +}; enum H5C_cache_decr_mode { H5C_decr__off, + /**<Automatic cache size decrease is disabled.*/ + H5C_decr__threshold, + /**<Automatic cache size decrease is enabled using the hit rate threshold algorithm.*/ + H5C_decr__age_out, + /**<Automatic cache size decrease is enabled using the ageout algorithm. */ + H5C_decr__age_out_with_threshold + /**<Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm.*/ }; #ifdef __cplusplus diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index a6f7d9b..1cfff22 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -47,22 +47,33 @@ /* Public Typedefs */ /*******************/ -/* Values for the H5D_LAYOUT property */ +//! <!-- [H5D_layout_t_snip] --> +/** + * Values for the H5D_LAYOUT property + */ typedef enum H5D_layout_t { H5D_LAYOUT_ERROR = -1, - H5D_COMPACT = 0, /*raw data is very small */ - H5D_CONTIGUOUS = 1, /*the default */ - H5D_CHUNKED = 2, /*slow and fancy */ - H5D_NLAYOUTS = 3 /*this one must be last! */ + H5D_COMPACT = 0, /**< raw data is very small */ + H5D_CONTIGUOUS = 1, /**< the default */ + H5D_CHUNKED = 2, /**< slow and fancy */ + H5D_NLAYOUTS = 3 /**< this one must be last! */ } H5D_layout_t; +//! <!-- [H5D_layout_t_snip] --> -/* Types of chunk index data structures */ +//! <!-- [H5D_chunk_index_t_snip] --> +/** + * Types of chunk index data structures + */ typedef enum H5D_chunk_index_t { - H5D_CHUNK_BTREE = 0 /* v1 B-tree index */ + H5D_CHUNK_BTREE = 0, /**< v1 B-tree index (default) */ } H5D_chunk_index_t; +//! <!-- [H5D_chunk_index_t_snip] --> -/* Values for the space allocation time property */ +//! <!-- [H5D_alloc_time_t_snip] --> +/** + * Values for the space allocation time property + */ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_ERROR = -1, H5D_ALLOC_TIME_DEFAULT = 0, @@ -70,30 +81,43 @@ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_LATE = 2, H5D_ALLOC_TIME_INCR = 3 } H5D_alloc_time_t; +//! <!-- [H5D_alloc_time_t_snip] --> -/* Values for the status of space allocation */ +//! <!-- [H5D_space_status_t_snip] --> +/** + * Values for the status of space allocation + */ typedef enum H5D_space_status_t { H5D_SPACE_STATUS_ERROR = -1, H5D_SPACE_STATUS_NOT_ALLOCATED = 0, H5D_SPACE_STATUS_PART_ALLOCATED = 1, H5D_SPACE_STATUS_ALLOCATED = 2 } H5D_space_status_t; +//! <!-- [H5D_space_status_t_snip] --> -/* Values for time of writing fill value property */ +//! <!-- [H5D_fill_time_t_snip] --> +/** + * Values for time of writing fill value property + */ typedef enum H5D_fill_time_t { H5D_FILL_TIME_ERROR = -1, H5D_FILL_TIME_ALLOC = 0, H5D_FILL_TIME_NEVER = 1, H5D_FILL_TIME_IFSET = 2 } H5D_fill_time_t; +//! <!-- [H5D_fill_time_t_snip] --> -/* Values for fill value status */ +//! <!-- [H5D_fill_value_t_snip] --> +/** + * Values for fill value status + */ typedef enum H5D_fill_value_t { H5D_FILL_VALUE_ERROR = -1, H5D_FILL_VALUE_UNDEFINED = 0, H5D_FILL_VALUE_DEFAULT = 1, H5D_FILL_VALUE_USER_DEFINED = 2 } H5D_fill_value_t; +//! <!-- [H5D_fill_value_t_snip] --> /********************/ /* Public Variables */ @@ -117,33 +141,1016 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b /* Define the operator function pointer for H5Dgather() */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); -H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, - hid_t dcpl_id, hid_t dapl_id); -H5_DLL hid_t H5Dcreate_anon(hid_t file_id, hid_t type_id, hid_t space_id, hid_t plist_id, hid_t dapl_id); -H5_DLL hid_t H5Dopen2(hid_t file_id, const char *name, hid_t dapl_id); -H5_DLL herr_t H5Dclose(hid_t dset_id); -H5_DLL hid_t H5Dget_space(hid_t dset_id); -H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); -H5_DLL hid_t H5Dget_type(hid_t dset_id); -H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); -H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Creates a new dataset and links it into the file + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to create + * \type_id + * \space_id + * \lcpl_id + * \dcpl_id + * \dapl_id + * + * \return \hid_t{dataset} + * + * \details H5Dcreate2() creates a new dataset named \p name at + * the location specified by \p loc_id, and associates constant + * and initial persistent properties with that dataset, including + * the datatype \p dtype_id, the dataspace \p space_id, and + * other properties as specified by the dataset creation property + * list \p dcpl_id and the access property list \p dapl_id, + * respectively. Once created, the dataset is opened for access. + * + * \p loc_id may specify a file, group, dataset, named datatype, + * or attribute. If an attribute, dataset, or named datatype is + * specified then the dataset will be created at the location + * where the attribute, dataset, or named datatype is attached. + * + * \p name may be either an absolute path in the file or a relative + * path from \p loc_id naming the dataset. + * + * \p dtype_id specifies the datatype of each data element as stored + * in the file. If \p dtype_id is either a fixed-length or + * variable-length string, it is important to set the string length + * when defining the datatype. String datatypes are derived from + * #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults + * to 1 character in size. + * + * If \p dtype_id is a committed datatype, and if the file location + * associated with the committed datatype is different from the + * file location where the dataset will be created, the datatype + * is copied and converted to a transient type. + * + * The link creation property list, \p lcpl_id, governs creation + * of the link(s) by which the new dataset is accessed and the + * creation of any * intermediate groups that may be missing. + * + * The datatype and dataspace properties and the dataset creation + * and access property lists are attached to the dataset, so the + * caller may derive new datatypes, dataspaces, and creation and + * access properties from the old ones and reuse them in calls to + * create additional datasets. Once created, the dataset can be + * read from or written to. Reading data from a datatset that was + * not previously written, the HDF5 library will return default + * or user-defined fill values. + * + * To conserve and release resources, the dataset should be closed + * when access is no longer required. + * + * \since 1.8.0 + * + * \see H5Dopen2(), H5Dclose(), H5Tset_size() + * + */ +H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, + hid_t dcpl_id, hid_t dapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Creates a dataset in a file without linking it into the file + * structure + * + * \fgdta_loc_id + * \type_id + * \space_id + * \dcpl_id + * \dapl_id + * + * \return \hid_t{dataset} + * + * \details H5Dcreate_anon() creates a dataset in the file specified + * by \p loc_id. + * + * \p loc_id may specify a file, group, dataset, named datatype, + * or attribute. If an attribute, dataset, or named datatype is + * specified then the dataset will be created at the location + * where the attribute, dataset, or named datatype is attached. + * + * The dataset’s datatype and dataspace are specified by + * \p type_id and \p space_id, respectively. These are the + * datatype and dataspace of the dataset as it will exist in + * the file, which may differ from the datatype and dataspace + * in application memory. + * + * Dataset creation property list and dataset access creation + * property list are specified by \p dcpl_id and \p dapl_id. + * + * H5Dcreate_anon() returns a new dataset identifier. Using + * this identifier, the new dataset must be linked into the + * HDF5 file structure with H5Olink() or it will be deleted + * from the file when the file is closed. + * + * See H5Dcreate2() for further details and considerations on + * the use of H5Dcreate2() and H5Dcreate_anon(). + * + * The differences between this function and H5Dcreate2() are + * as follows: + * \li H5Dcreate_anon() explicitly includes a dataset access property + * list. H5Dcreate() always uses default dataset access properties. + * + * \li H5Dcreate_anon() neither provides the new dataset’s name nor + * links it into the HDF5 file structure; those actions must be + * performed separately through a call to H5Olink(), which offers + * greater control over linking. + * + * A dataset created with this function should be closed with + * H5Dclose() when the dataset is no longer needed so that resource + * leaks will not develop. + * + * \since 1.8.0 + * + * \see H5Olink(), H5Dcreate(), Using Identifiers + * + */ +H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Creates a new dataset and links it into the file + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to open + * \dapl_id + * + * \return \hid_t{dataset} + * + * \details H5Dopen2() opens the existing dataset specified + * by a location identifier and name, \p loc_id and \p name, + * respectively. + * + * \p loc_id may specify a file, group, dataset, named datatype, + * or attribute. If an attribute, dataset, or named datatype is + * specified then the dataset will be opened at the location + * where the attribute, dataset, or named datatype is attached. + * + * The dataset access property list, \p dapl_id, provides + * information regarding access to the dataset. + * + * To conserve and release resources, the dataset should be closed + * when access is no longer required. + * + * \since 1.8.0 + * + * \see H5Dcreate2(), H5Dclose() + * + */ +H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); + +/** + * -------------------------------------------------------------------------- + *\ingroup H5D + * + * \brief Returns an identifier for a copy of the dataspace for a dataset + * + * \dset_id + * + * \return \hid_t{dataspace} + * + * \details H5Dget_space() makes a copy of the dataspace of + * the dataset specified by \p dset_id. The function returns an + * identifier for the new copy of the dataspace. + * + * A dataspace identifier returned from this function should + * be released with H5Sclose() when the identifier is no longer + * needed so that resource leaks will not occur. + * + * \see H5Sclose() + * + */ +H5_DLL hid_t H5Dget_space(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * \todo Document this function! + */ +H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns an identifier for a copy of the datatype for a dataset + * + * \dset_id + * + * \return \hid_t{datatype} + * + * \details H5Dget_type() returns an identifier of a copy of + * the datatype for a dataset. + * + * If a dataset has a named datatype, then an identifier to the + * opened datatype is returned. Otherwise, the returned datatype + * is read-only. If atomization of the datatype fails, then the + * datatype is closed. + * + * A datatype identifier returned from this function should be + * released with H5Tclose() when the identifier is no longer + * needed to prevent resource leaks. + * + * \note Datatype Identifiers + * + * Please note that the datatype identifier is actually an object + * identifier or a handle returned from opening the datatype. It + * is not persistent and its value can be different from one HDF5 + * session to the next. + * + * H5Tequal() can be used to compare datatypes. + * + * HDF5 High Level APIs that may also be of interest are: + * + * H5LTdtype_to_text() creates a text description of a + * datatype. H5LTtext_to_dtype() creates an HDF5 datatype + * given a text description. + * + */ +H5_DLL hid_t H5Dget_type(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns an identifier for a copy of the dataset creation + * property list for a dataset + * + * \dset_id + * + * \return \hid_t{dataset creation property list} + * + * \details H5Dget_create_plist() returns an identifier for + * a copy of the dataset creation property list associated with + * the dataset specified by \p dset_id. + * + * The creation property list identifier should be released + * with H5Pclose() to prevent resource leaks. + * + */ +H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns the dataset access property list associated with + * a dataset + * + * \dset_id + * + * \return \hid_t{dataset access property list} + * + * \details H5Dget_access_plist() returns a copy of the + * dataset access property list used to open the specified + * dataset, \p dset_id. Modifications to the returned property + * list will have no effect on the dataset it was retrieved from. + * + * The chunk cache parameters in the returned property lists will + * be those used by the dataset. If the properties in the file + * access property list were used to determine the dataset's + * chunk cache configuration, then those properties will be + * present in the returned dataset access property list. If + * the dataset does not use a chunked layout, then the chunk + * cache properties will be set to the default. The chunk cache + * properties in the returned list are considered to be “set”, + * and any use of this list will override the corresponding + * properties in the file’s file access property list. + * + * All link access properties in the returned list will be set + * to the default values. + * + * The access property list identifier should be released with + * H5Pclose() when the identifier is no longer needed so that + * resource leaks will not develop. + * + * \since 1.8.3 + * + */ +H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns the amount of storage allocated for a dataset + * + * \dset_id + * + * \return Returns the amount of storage space, in bytes, or 0 (zero). + * + * \details H5Dget_storage_size() returns the amount of storage, + * in bytes, that is allocated in the file for the raw data of + * the dataset specified by \p dset_id. + * + * \note The amount of storage in this case is the storage + * allocated in the written file, which will typically differ + * from the space required to hold a dataset in working memory. + * + * \li For contiguous datasets, the returned size equals the current + * allocated size of the raw data. + * \li For unfiltered chunked datasets, the returned size is the + * number of allocated chunks times the chunk size. + * \li For filtered chunked datasets, the returned size is the + * space required to store the filtered data. For example, if a + * compression filter is in use, H5Dget_storage_size() will return + * the total space required to store the compressed chunks. + * + * H5Dget_storage_size() reports only the space required to store + * the data, not including that of any metadata. + * + * \attention H5Dget_storage_size() does not differentiate between 0 (zero), + * the value returned for the storage size of a dataset + * with no stored values, and 0 (zero), the value returned to + * indicate an error. + * + * \note Note that H5Dget_storage_size() is not generally an + * appropriate function to use when determining the amount + * of memory required to work with a dataset. In such + * circumstances, you must determine the number of data + * points in a dataset and the size of an individual data + * element. H5Sget_simple_extent_npoints() and H5Tget_size() + * can be used to get that information. + * + */ H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id); -H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_bytes); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns the amount of storage allocated within the file for a + * raw data chunk in a dataset + * + * \dset_id + * \param[in] offset Logical offset in the dataset for the chunk to query + * \param[out] chunk_bytes The size in bytes for the chunk + * + * \return \herr_t + * + * \details H5Dget_chunk_storage_size() returns the size in bytes + * allocated in the file for a raw data chunk as specified by + * its logical \p offset in the dataset \p dset_id. The size is + * returned in \p chunk_nbytes. It is the size of the compressed + * data if the chunk is filtered and the size may be zero if no + * storage is allocated yet for the dataset. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_bytes); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Returns dataset address in file + * + * \dset_id + * + * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF, + * a negative value. + * + * \details H5Dget_offset() returns the address in the file of + * the dataset, \p dset_id. That address is expressed as the + * offset in bytes from the beginning of the file. + * + * \since 1.6.0 + * + */ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); -H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, - hid_t plist_id, void *buf /*out*/); -H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, - hid_t plist_id, const void *buf); -H5_DLL herr_t H5Diterate(void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *operator_data); -H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf); -H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size); -H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type, void *buf, hid_t buf_type, hid_t space); -H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); -H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id, - void *dst_buf); -H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, - void *dst_buf, H5D_gather_func_t op, void *op_data); -H5_DLL herr_t H5Ddebug(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Reads raw data from a dataset into a provided buffer + * + * \dset_id Identifier of the dataset to read from + * \param[in] mem_type_id Identifier of the memory datatype + * \param[in] mem_space_id Identifier of the memory dataspace + * \param[in] file_space_id Identifier of the dataset's dataspace in the file + * \param[in] dxpl_id Identifier of a transfer property list + * \param[out] buf Buffer to receive data read from file + * + * \return \herr_t + * + * \details H5Dread() reads a dataset, specified by its identifier + * \p dset_id, from the file into an application memory buffer \p + * buf. Data transfer properties are defined by the argument \p + * dxpl_id. The memory datatype of the (partial) dataset + * is identified by the identifier \p mem_type_id. The part + * of the dataset to read is defined by \p mem_space_id and \p + * file_space_id. + * + * \p file_space_id is used to specify only the selection within + * the file dataset's dataspace. Any dataspace specified in \p + * file_space_id is ignored by the library and the dataset's + * dataspace is always used. \p file_space_id can be the constant + * #H5S_ALL, which indicates that the entire file dataspace, + * as defined by the current dimensions of the dataset, is to + * be selected. + * + * \p mem_space_id is used to specify both the memory dataspace + * and the selection within that dataspace. \p mem_space_id can + * be the constant #H5S_ALL, in which case the file dataspace is + * used for the memory dataspace and the selection defined with \p + * file_space_id is used for the selection within that dataspace. + * + * If raw data storage space has not been allocated for the dataset + * and a fill value has been defined, the returned buffer \p buf + * is filled with the fill value. + * + * The behavior of the library for the various combinations of + * valid dataspace identifiers and #H5S_ALL for the \p mem_space_id + * and the \p file_space_id parameters is described below: + * + * <table> + * <tr> + * <th>mem_space_id</th> + * <th>file_space_id</th> + * <th>Behavior</th> + * </tr> + * <tr> + * <td>valid dataspace ID</td> + * <td>valid dataspace ID</td> + * <td>\p mem_space_id specifies the memory dataspace and the + * selection within it. \p file_space_id specifies the + * selection within the file dataset's dataspace.</td> + * </tr> + * <tr> + * <td>#H5S_ALL</td> + * <td>valid dataspace ID</td> + * <td>The file dataset's dataspace is used for the memory + * dataspace and the selection specified with \p file_space_id + * specifies the selection within it. The combination of the + * file dataset's dataspace and the selection from + * \p file_space_id is used for memory also.</td> + * </tr> + * <tr> + * <td>valid dataspace ID</td> + * <td>#H5S_ALL</td> + * <td>\p mem_space_id specifies the memory dataspace and the + * selection within it. The selection within the file + * dataset's dataspace is set to the "all" selection.</td> + * </tr> + * <tr> + * <td>#H5S_ALL</td> + * <td>#H5S_ALL</td> + * <td>The file dataset's dataspace is used for the memory + * dataspace and the selection within the memory dataspace + * is set to the "all" selection. The selection within the + * file dataset's dataspace is set to the "all" selection.</td> + * </tr> + * </table> + * + * \details Setting an #H5S_ALL selection indicates that the entire + * dataspace, as defined by the current dimensions of a dataspace, + * will be selected. The number of elements selected in the memory + * dataspace must match the number of elements selected in the + * file dataspace. + * + * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the + * default data transfer properties are used. + * + */ +H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, + hid_t dxpl_id, void *buf /*out*/); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Writes raw data from a buffer to a dataset + * + * \param[in] dset_id Identifier of the dataset to read from + * \param[in] mem_type_id Identifier of the memory datatype + * \param[in] mem_space_id Identifier of the memory dataspace + * \param[in] file_space_id Identifier of the dataset's dataspace in the file + * \dxpl_id + * \param[out] buf Buffer with data to be written to the file + * + * \return \herr_t + * + * \details H5Dwrite() writes a (partial) dataset, specified by + * its identifier \p dset_id, from the application memory buffer \p + * buf into the file. Data transfer properties are defined by the + * argument \p dxpl_id. The memory datatype of the (partial) + * dataset is identified by the identifier \p mem_type_id. The + * part of the dataset to write is defined by \p mem_space_id + * and \p file_space_id. + * + * If \p mem_type_id is either a fixed-length or variable-length + * string, it is important to set the string length when defining + * the datatype. String datatypes are derived from #H5T_C_S1 + * (or #H5T_FORTRAN_S1 for Fortran codes), which defaults + * to 1 character in size. See H5Tset_size() and Creating + * variable-length string datatypes. + * + * \p file_space_id is used to specify only the selection within + * the file dataset's dataspace. Any dataspace specified in \p + * file_space_id is ignored by the library and the dataset's + * dataspace is always used. \p file_space_id can be the constant + * #H5S_ALL, which indicates that the entire file dataspace, + * as defined by the current dimensions of the dataset, is to + * be selected. + * + * \p mem_space_id is used to specify both the memory dataspace + * and the selection within that dataspace. mem_space_id can be + * the constant #H5S_ALL, in which case the file dataspace is + * used for the memory dataspace and the selection defined with \p + * file_space_id is used for the selection within that dataspace. + * + * The behavior of the library for the various combinations of + * valid dataspace IDs and #H5S_ALL for the mem_space_id and + * thefile_space_id parameters is described below: + * + * <table> + * <tr><th>\c mem_space_id</th> + * <th>\c file_space_id</th> + * <th>Behavior</th></tr> + * <tr><td>valid dataspace ID</td> + * <td>valid dataspace ID</td> + * <td>\p mem_space_id specifies the memory dataspace and the + * selection within it. \p file_space_id specifies the + * selection within the file dataset's dataspace.</td></tr> + * <tr><td>#H5S_ALL</td> + * <td>valid dataspace ID</td> + * <td>The file dataset's dataspace is used for the memory + * dataspace and the selection specified with \p file_space_id + * specifies the selection within it. The combination of the + * file dataset's dataspace and the selection from \p + * file_space_id is used for memory also. valid dataspace + * ID</td></tr> + * <tr><td>valid dataspace ID</td> + * <td>#H5S_ALL</td> + * <td>\p mem_space_id specifies the memory dataspace and the + * selection within it. The selection within the file + * dataset's dataspace is set to "all" selection.</td></tr> + * <tr><td>#H5S_ALL</td> + * <td>#H5S_ALL</td> + * <td>The file dataset's dataspace is used for the memory + * dataspace and the selection within the memory dataspace is + * set to the "all" selection. The selection within the file + * dataset's dataspace is set to the "all" + * selection.</td></tr> + * </table> + * Setting an "all" selection indicates that the entire dataspace, + * as defined by the current dimensions of a dataspace, will + * be selected. The number of elements selected in the memory + * dataspace must match the number of elements selected in the + * file dataspace. + * + * \p dxpl_id can be the constant #H5P_DEFAULT, in which + * case the default data transfer properties are used. + * + * Writing to a dataset will fail if the HDF5 file was not opened + * with write access permissions. + * + * If the dataset's space allocation time is set to + * #H5D_ALLOC_TIME_LATE or #H5D_ALLOC_TIME_INCR and the space for + * the dataset has not yet been allocated, that space is allocated + * when the first raw data is written to the dataset. Unused space + * in the dataset will be written with fill values at the same + * time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET + * or #H5D_FILL_TIME_ALLOC. + * + * \attention If a dataset's storage layout is 'compact', care must be + * taken when writing data to the dataset in parallel. A compact + * dataset's raw data is cached in memory and may be flushed + * to the file from any of the parallel processes, so parallel + * applications should always attempt to write identical data to + * the dataset from all processes. + * + * \see H5Pset_fill_time(), H5Pset_alloc_time() + * + */ +H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, + hid_t dxpl_id, const void *buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Iterates over all selected elements in a dataspace + * + * \param[in,out] buf Buffer containing the elements to iterate over + * \type_id + * \space_id + * \param[in] op Function pointer + * \param[in,out] operator_data User-defined data + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Diterate() iterates over all the data elements + * in the memory buffer \p buf, executing the callback function + * \p op once for each such data element. + * + * The prototype of the callback function \p op is as follows + * (as defined in the source code file H5Lpublic.h): + * \snippet this H5D_operator_t_snip + * The parameters of this callback function are: + * + * <table> + * <tr><td>\c elem</td> + * <td><tt>[in,out]</tt></td> + * <td>Pointer to the memory buffer containing the current + * data element</td></tr> + * <tr><td>\c type_id</td> + * <td><tt>[in]</tt></td> + * <td>Datatype identifier of the elements stored in elem</td></tr> + * <tr><td>\c ndim</td> + * <td><tt>[in]</tt></td> + * <td>Number of dimensions for the point array</td></tr> + * <tr><td>\c point</td> + * <td><tt>[in]</tt></td> + * <td>Array containing the location of the element within + * the original dataspace</td></tr> + * <tr><td>\c operator_data</td> + * <td><tt>[in,out]</tt></td> + * <td>Pointer to any user-defined data associated with the + * operation</td></tr> + * </table> + * + * The possible return values from the callback function, and + * the effect ofeach,are as follows: + * + * \li Zero causes the iterator to continue, returning zero + * when all data elements have been processed. + * \li A positive value causes the iterator to immediately + * return that positive value, indicating short-circuit success. + * \li A negative value causes the iterator to immediately return + * that value, indicating failure. + * + * The \p operator_data parameter is a user-defined pointer to + * the data required to process dataset elements in the course + * of the iteration. If operator needs to pass data back to the + * application, such data can be returned in this same buffer. This + * pointer is passed back to each step of the iteration in the + * operator callback function’s operator_data parameter. + * + * Unlike other HDF5 iterators, this iteration operation cannot + * be restarted at the point of exit; a second H5Diterate() + * call will always restart at the beginning. + * + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Diterate(void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *operator_data); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Reclaims variable-length (VL) datatype memory buffers + * + * \type_id + * \space_id + * \dxpl_id + * \param[in] buf Pointer to the buffer to be reclaimed + * + * \return \herr_t + * + * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL + * datatypes. + * + * The \p type_id must be the datatype stored in the buffer. The \p + * space_id describes the selection for the memory buffer to free the + * VL datatypes within. The \p dxpl_id is the dataset transfer property + * list which was used for the I/O transfer to create the buffer. And + * \p buf is the pointer to the buffer to be reclaimed. + * + * The VL structures (\ref hvl_t) in the user's buffer are modified to + * zero out the VL information after the memory has been reclaimed. + * + * If nested VL datatypes were used to create the buffer, this routine + * frees them from the bottom up, releasing all the memory without + * creating memory leaks. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Determines the number of bytes required to store variable-length + * (VL) data + * + * \dset_id + * \type_id + * \space_id + * \param[out] size Size in bytes of the memory buffer required to store + * the VL data + * + * \return \herr_t + * + * \details H5Dvlen_get_buf_size() determines the number of bytes + * required to store the VL data from the dataset, using \p + * space_id for the selection in the dataset on disk and the \p + * type_id for the memory representation of the VL data in memory. + * \p size is returned with the number of bytes required to store + * the VL data in memory. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, hsize_t *size); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Fills dataspace elements with a fill value in a memory buffer + * + * \param[in] fill Pointer to the fill value to be used + * \param[in] fill_type_id Fill value datatype identifier + * \param[in,out] buf Pointer to the memory buffer containing the + * selection to be filled + * \param[in] buf_type_id Datatype of dataspace elements to be filled + * \space_id + * + * \return \herr_t + * + * \details H5Dfill() fills the dataspace selection in memory, \p space_id, + * with the fill value specified in \p fill. If \p fill is NULL, + * a fill value of 0 (zero) is used. + * + * \p fill_type_id specifies the datatype of the fill value. + * \p buf specifies the buffer in which the dataspace elements + * will be written. + * \p buf_type_id specifies the datatype of those data elements. + * + * \note Note that if the fill value datatype differs from the memory + * buffer datatype, the fill value will be converted to the memory + * buffer datatype before filling the selection. + * + * \note Applications sometimes write data only to portions of an + * allocated dataset. It is often useful in such cases to fill + * the unused space with a known fill value. See the following + * function for more information: + * - H5Pset_fill_value() + * - H5Pget_fill_value() + * - H5Pfill_value_defined() + * - H5Pset_fill_time() + * - H5Pget_fill_time() + * - H5Pcreate() + * - H5Pcreate_anon() + * + */ +H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Changes the sizes of a dataset’s dimensions + * + * \dset_id + * \param[in] size[] Array containing the new magnitude of each dimension + * of the dataset + * + * \return \herr_t + * + * \details H5Dset_extent() sets the current dimensions of the + * chunked dataset \p dset_id to the sizes specified in size. + * + * \p size is a 1-dimensional array with n elements, where \p n is + * the rank of the dataset’s current dataspace. + * + * This function can be applied to the following datasets: + * - A chunked dataset with unlimited dimensions + * - A chunked dataset with fixed dimensions if the new dimension + * sizes are less than the maximum sizes set with maxdims (see + * H5Screate_simple()) + * - An external dataset with unlimited dimensions + * - An external dataset with fixed dimensions if the new dimension + * sizes are less than the maximum sizes set with \p maxdims + * + * Note that external datasets are always contiguous and can be + * extended only along the first dimension. + * + * Space on disk is immediately allocated for the new dataset extent if + * the dataset’s space allocation time is set to #H5D_ALLOC_TIME_EARLY. + * + * Fill values will be written to the dataset in either of the + * following situations, but not otherwise: + * + * - If the dataset’s fill time is set to #H5D_FILL_TIME_IFSET and a + * fill value is defined (see H5Pset_fill_time() and + * H5Pset_fill_value()) + * - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC + * (see H5Pset_alloc_time()) + * + * \note + * \li If the sizes specified in \p size array are smaller than + * the dataset’s current dimension sizes, H5Dset_extent() will reduce + * the dataset’s dimension sizes to the specified values. It is the + * user application’s responsibility to ensure that valuable data is + * not lost as H5Dset_extent() does not check. + * + * \li Except for external datasets, H5Dset_extent() is for use with + * chunked datasets only, not contiguous datasets. + * + * \li A call to H5Dset_extent() affects the dataspace of a dataset. + * If a dataspace handle was opened for a dataset prior to a call to + * H5Dset_extent() then that dataspace handle will no longer reflect + * the correct dataspace extent of the dataset. H5Dget_space() must + * be called (after closing the previous handle) to obtain the current + * dataspace extent. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Scatters data into a selection within a memory buffer + * + * \param[in] op Callback function which provides data to be scattered + * \param[in] op_data User-defined pointer to data required by op + * \param[in] type_id Identifier for the datatype describing the data in + * both the source and destination buffers + * \param[in] dst_space_id Identifier for the dataspace for destination + * \param[out] dst_buf Destination buffer which the data will be scattered to + * + * \return \herr_t + * + * \details H5Dscatter() retrieves data from the supplied callback + * \p op and scatters it to the supplied buffer \p dst_buf in a + * manner similar to data being written to a dataset. + * + * \p dst_space_id is a dataspace which defines the extent of \p + * dst_buf and the selection within it to scatter the data to. + * + * \p type_id is the datatype of the data to be scattered in both + * the source and destination buffers. + * + * \p dst_buf must be at least as large as the number of elements + * in the extent of \p dst_space_id times the size in bytes of + * \p type_id. + * + * To retrieve the data to be scattered, H5Dscatter() repeatedly + * calls \p op, which should return a valid source buffer, until + * enough data to fill the selection has been retrieved. The + * prototype of the callback function \p op is as follows (as + * defined in the source code file H5Dpublic.h): + * \snippet this H5D_scatter_func_t_snip + * The parameters of this callback function are described below: + * + * <table> + * <tr><td>\c src_buf</td> + * <td><tt>[out]</tt></td> + * <td>Pointer to the buffer holding the next set of elements to + * scatter. On entry, the value of where \c src_buf points to + * is undefined. The callback function should set \c src_buf + * to point to the next set of elements.</td></tr> + * <tr><td>\c src_buf_bytes_used</td> + * <td><tt>[out]</tt></td> + * <td>Pointer to the number of valid bytes in \c src_buf. On + * entry, the value where \c src_buf_bytes_used points to is + * undefined. The callback function should set + * \c src_buf_bytes_used to the of valid bytes in \c src_buf. + * This number must be a multiple of the datatype size. + * </td></tr> + * <tr><td>\c op_data</td> + * <td><tt>[in,out]</tt></td> + * <td>User-defined pointer to data required by the callback + * function. A pass-through of the \c op_data pointer provided + * with the H5Dscatter() function call.</td></tr> + * </table> + * + * The callback function should always return at least one + * element in \p src_buf, and must not return more elements + * than are remaining to be scattered. This function will be + * repeatedly called until all elements to be scattered have + * been returned. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id, + void *dst_buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Gathers data from a selection within a memory buffer + * raw data chunk in a dataset + * + * \param[in] src_space_id Dataspace identifier for the source buffer + * \param[in] src_buf Source buffer which the data will be gathered from + * \param[in] type_id Datatype identifier for the source + * \param[in] dst_buf_size Size in bytes of \p dst_buf + * \param[out] dst_buf Destination buffer for the gathered data + * \param[in] op Callback function which handles the gathered data + * \param[in] op_data User-defined pointer to data required by \p op + * + * \return \herr_t + * + * \details H5Dgather() retrieves data from a selection within the supplied + * buffer src_buf and passes it to the supplied callback function + * \p op in a contiguous form. + * + * The dataspace \p src_space_id describes both the dimensions of + * the source buffer and the selection within the source buffer + * to gather data from. + * + * \p src_buf must be at least the size of the gathered data, that + * is, the number of elements in the extent of \p src_space_id + * times the size in bytes of \p type_id. + * + * The datatype \p type_id describes the data in both the source + * and destination buffers. This information is used to calculate + * the element size. + * + * The data is gathered into \p dst_buf, which needs to be large + * enough to hold all the data if the callback function \p op is + * not provided. + * + * \p op is a callback function which handles the gathered data. + * It is optional if \p dst_buf is large enough to hold all of the + * gathered data; required otherwise. + * + * If no callback function is provided, H5Dgather() simply gathers + * the data into \p dst_buf and returns. If a callback function is + * provided, H5Dgather() repeatedly gathers up to \p dst_buf_size + * bytes to process the serialized data. The prototype of the + * callback function \p op is as follows (as defined in the source + * code file H5Dpublic.h): + * \snippet this H5D_gather_func_t_snip + * The parameters of this callback function are described in the + * table below. + * <table> + * <tr><td>\c dst_buf</td> + * <td>Pointer to the destination buffer which has been filled + * with the next set of elements gathered. This will always be + * identical to the \p dst_buf passed to H5Dgather().</td></tr> + * <tr><td>\c dst_buf_bytes_used</td> + * <td>Pointer to the number of valid bytes in \p dst_buf. + * This number must be a multiple of the datatype + * size.</td></tr> + * <tr><td>\c op_data</td> + * <td>User-defined pointer to data required by the callback + * function; a pass-through of the \p op_data pointer + * provided with the H5Dgather() function call.</td></tr> + * </table> + * The callback function should process, store, or otherwise, + * make use of the data returned in \p dst_buf before it returns, + * because the buffer will be overwritten unless it is the last + * call to the callback. This function will be repeatedly called + * until all gathered elements have been passed to the callback + * in \p dst_buf. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, + void *dst_buf, H5D_gather_func_t op, void *op_data); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Closes the specified dataset + * + * \dset_id + * + * \return \herr_t + * + * \details H5Dclose() ends access to a dataset specified by \p dset_id + * and releases resources used by it. + * + * \attention Further use of a released dataset identifier is illegal; a + * function using such an identifier will generate an error. + * + * \since 1.8.0 + * + * \see H5Dcreate2(), H5Dopen2() + * + */ +H5_DLL herr_t H5Dclose(hid_t dset_id); + +/* Internal API routines */ +H5_DLL herr_t H5Ddebug(hid_t dset_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -156,8 +1163,145 @@ H5_DLL herr_t H5Ddebug(hid_t dset_id); /* Typedefs */ /* Function prototypes */ -H5_DLL hid_t H5Dcreate1(hid_t file_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id); -H5_DLL hid_t H5Dopen1(hid_t file_id, const char *name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Creates a dataset at the specified location + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to create + * \type_id + * \space_id + * \dcpl_id + * + * \return \hid_t{dataset} + * + * \deprecated This function is deprecated in favor of the function H5Dcreate2() + * or the macro H5Dcreate(). + * + * \details H5Dcreate1() creates a data set with a name, \p name, in the + * location specified by the identifier \p loc_id. \p loc_id may be a + * file, group, dataset, named datatype or attribute. If an attribute, + * dataset, or named datatype is specified for \p loc_id then the + * dataset will be created at the location where the attribute, + * dataset, or named datatype is attached. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires that + * any intermediate groups specified in the path already exist. + * + * The dataset’s datatype and dataspace are specified by \p type_id and + * \p space_id, respectively. These are the datatype and dataspace of + * the dataset as it will exist in the file, which may differ from the + * datatype and dataspace in application memory. + * + * Names within a group are unique: H5Dcreate1() will return an error + * if a link with the name specified in name already exists at the + * location specified in \p loc_id. + * + * As is the case for any object in a group, the length of a dataset + * name is not limited. + * + * \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p + * H5reate1() and initialized with various property list functions + * described in Property List Interface. + * + * H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s + * datatype includes a variable-length (VL) datatype and the fill value + * is undefined, i.e., set to \c NULL in the dataset creation property + * list. Such a VL datatype may be directly included, indirectly + * included as part of a compound or array datatype, or indirectly + * included as part of a nested compound or array datatype. + * + * H5Dcreate() and H5Dcreate_anon() return a dataset identifier for + * success or a negative value for failure. The dataset identifier + * should eventually be closed by calling H5Dclose() to release + * resources it uses. + * + * See H5Dcreate_anon() for discussion of the differences between + * H5Dcreate() and H5Dcreate_anon(). + * + * The HDF5 library provides flexible means of specifying a fill value, + * of specifying when space will be allocated for a dataset, and of + * specifying when fill values will be written to a dataset. + * + * \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release. + * \since 1.0.0 + * + * \see H5Dopen2(), H5Dclose(), H5Tset_size() + * + */ +H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Opens an existing dataset + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to access + * + * \return \hid_t{dataset} + * + * \deprecated This function is deprecated in favor of the function H5Dopen2() + * or the macro H5Dopen(). + * + * \details H5Dopen1() opens an existing dataset for access at the location + * specified by \p loc_id. \p loc_id may be a file, group, dataset, + * named datatype or attribute. If an attribute, dataset, or named + * datatype is specified for loc_id then the dataset will be opened at + * the location where the attribute, dataset, or named datatype is + * attached. name is a dataset name and is used to identify the dataset + * in the file. + * + * A dataset opened with this function should be closed with H5Dclose() + * when the dataset is no longer needed so that resource leaks will not + * develop. + * + * \version 1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Extends a dataset + * + * \dset_id + * \param[in] size Array containing the new size of each dimension + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * + * \details H5Dextend() verifies that the dataset is at least of size \p size, + * extending it if necessary. The dimensionality of size is the same as + * that of the dataspace of the dataset being changed. + * + * This function can be applied to the following datasets: + * \li Any dataset with unlimited dimensions + * \li A dataset with fixed dimensions if the current dimension sizes + * are less than the maximum sizes set with \c maxdims + * (see H5Screate_simple()) + * + * Space on disk is immediately allocated for the new dataset extent if + * the dataset’s space allocation time is set to + * #H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if + * the dataset’s fill time is set to #H5D_FILL_TIME_IFSET or + * #H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and + * H5Pset_alloc_time().) + * + * This function ensures that the dataset dimensions are of at least + * the sizes specified in size. The function H5Dset_extent() must be + * used if the dataset dimension sizes are are to be reduced. + * + * \version 1.8.0 Function Function deprecated in this release. Parameter size + * syntax changed to \Code{const hsize_t size[]} in this release. + * + */ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Edefin.h b/src/H5Edefin.h index 7a5b428..c34435a 100644 --- a/src/H5Edefin.h +++ b/src/H5Edefin.h @@ -19,47 +19,103 @@ #define H5Edefin_H /* Major error IDs */ -hid_t H5E_LINK_g = FAIL; /* Links */ -hid_t H5E_FILE_g = FAIL; /* File accessibility */ -hid_t H5E_INTERNAL_g = FAIL; /* Internal error (too specific to document in detail) */ -hid_t H5E_ARGS_g = FAIL; /* Invalid arguments to routine */ -hid_t H5E_DATASPACE_g = FAIL; /* Dataspace */ hid_t H5E_SYM_g = FAIL; /* Symbol table */ -hid_t H5E_RESOURCE_g = FAIL; /* Resource unavailable */ -hid_t H5E_SLIST_g = FAIL; /* Skip Lists */ -hid_t H5E_DATASET_g = FAIL; /* Dataset */ -hid_t H5E_STORAGE_g = FAIL; /* Data storage */ -hid_t H5E_EFL_g = FAIL; /* External file list */ -hid_t H5E_PLINE_g = FAIL; /* Data filters */ +hid_t H5E_FILE_g = FAIL; /* File accessibility */ hid_t H5E_DATATYPE_g = FAIL; /* Datatype */ +hid_t H5E_LINK_g = FAIL; /* Links */ +hid_t H5E_DATASET_g = FAIL; /* Dataset */ hid_t H5E_ATOM_g = FAIL; /* Object atom */ +hid_t H5E_RESOURCE_g = FAIL; /* Resource unavailable */ +hid_t H5E_INTERNAL_g = FAIL; /* Internal error (too specific to document in detail) */ hid_t H5E_CACHE_g = FAIL; /* Object cache */ -hid_t H5E_ERROR_g = FAIL; /* Error API */ -hid_t H5E_OHDR_g = FAIL; /* Object header */ -hid_t H5E_IO_g = FAIL; /* Low-level I/O */ hid_t H5E_SOHM_g = FAIL; /* Shared Object Header Messages */ -hid_t H5E_RS_g = FAIL; /* Reference Counted Strings */ -hid_t H5E_PLUGIN_g = FAIL; /* Plugin for dynamically loaded library */ -hid_t H5E_TST_g = FAIL; /* Ternary Search Trees */ -hid_t H5E_FSPACE_g = FAIL; /* Free Space Manager */ -hid_t H5E_BTREE_g = FAIL; /* B-Tree node */ -hid_t H5E_REFERENCE_g = FAIL; /* References */ hid_t H5E_FUNC_g = FAIL; /* Function entry/exit */ -hid_t H5E_VFL_g = FAIL; /* Virtual File Layer */ +hid_t H5E_RS_g = FAIL; /* Reference Counted Strings */ hid_t H5E_PLIST_g = FAIL; /* Property lists */ -hid_t H5E_HEAP_g = FAIL; /* Heap */ +hid_t H5E_BTREE_g = FAIL; /* B-Tree node */ hid_t H5E_NONE_MAJOR_g = FAIL; /* No error */ +hid_t H5E_SLIST_g = FAIL; /* Skip Lists */ +hid_t H5E_DATASPACE_g = FAIL; /* Dataspace */ +hid_t H5E_ARGS_g = FAIL; /* Invalid arguments to routine */ +hid_t H5E_REFERENCE_g = FAIL; /* References */ +hid_t H5E_FSPACE_g = FAIL; /* Free Space Manager */ +hid_t H5E_EFL_g = FAIL; /* External file list */ +hid_t H5E_PLINE_g = FAIL; /* Data filters */ +hid_t H5E_ERROR_g = FAIL; /* Error API */ hid_t H5E_ATTR_g = FAIL; /* Attribute */ +hid_t H5E_HEAP_g = FAIL; /* Heap */ +hid_t H5E_VFL_g = FAIL; /* Virtual File Layer */ +hid_t H5E_OHDR_g = FAIL; /* Object header */ +hid_t H5E_IO_g = FAIL; /* Low-level I/O */ +hid_t H5E_TST_g = FAIL; /* Ternary Search Trees */ +hid_t H5E_STORAGE_g = FAIL; /* Data storage */ +hid_t H5E_PLUGIN_g = FAIL; /* Plugin for dynamically loaded library */ /* Minor error IDs */ -/* Object atom related errors */ -hid_t H5E_BADATOM_g = FAIL; /* Unable to find atom information (already closed?) */ -hid_t H5E_BADGROUP_g = FAIL; /* Unable to find ID group information */ -hid_t H5E_CANTREGISTER_g = FAIL; /* Unable to register new atom */ -hid_t H5E_CANTINC_g = FAIL; /* Unable to increment reference count */ -hid_t H5E_CANTDEC_g = FAIL; /* Unable to decrement reference count */ -hid_t H5E_NOIDS_g = FAIL; /* Out of IDs for group */ +/* Heap errors */ +hid_t H5E_CANTRESTORE_g = FAIL; /* Can't restore condition */ +hid_t H5E_CANTCOMPUTE_g = FAIL; /* Can't compute value */ +hid_t H5E_CANTEXTEND_g = FAIL; /* Can't extend heap's space */ +hid_t H5E_CANTATTACH_g = FAIL; /* Can't attach object */ +hid_t H5E_CANTUPDATE_g = FAIL; /* Can't update object */ +hid_t H5E_CANTOPERATE_g = FAIL; /* Can't operate on object */ + +/* No error */ +hid_t H5E_NONE_MINOR_g = FAIL; /* No error */ + +/* Link related errors */ +hid_t H5E_TRAVERSE_g = FAIL; /* Link traversal failure */ +hid_t H5E_NLINKS_g = FAIL; /* Too many soft links in path */ +hid_t H5E_NOTREGISTERED_g = FAIL; /* Link class not registered */ +hid_t H5E_CANTMOVE_g = FAIL; /* Can't move object */ +hid_t H5E_CANTSORT_g = FAIL; /* Can't sort objects */ + +/* I/O pipeline errors */ +hid_t H5E_NOFILTER_g = FAIL; /* Requested filter is not available */ +hid_t H5E_CALLBACK_g = FAIL; /* Callback failed */ +hid_t H5E_CANAPPLY_g = FAIL; /* Error from filter 'can apply' callback */ +hid_t H5E_SETLOCAL_g = FAIL; /* Error from filter 'set local' callback */ +hid_t H5E_NOENCODER_g = FAIL; /* Filter present but encoding disabled */ +hid_t H5E_CANTFILTER_g = FAIL; /* Filter operation failed */ + +/* System level errors */ +hid_t H5E_SYSERRSTR_g = FAIL; /* System error message */ + +/* Argument errors */ +hid_t H5E_UNINITIALIZED_g = FAIL; /* Information is uinitialized */ +hid_t H5E_UNSUPPORTED_g = FAIL; /* Feature is unsupported */ +hid_t H5E_BADTYPE_g = FAIL; /* Inappropriate type */ +hid_t H5E_BADRANGE_g = FAIL; /* Out of range */ +hid_t H5E_BADVALUE_g = FAIL; /* Bad value */ + +/* Group related errors */ +hid_t H5E_CANTOPENOBJ_g = FAIL; /* Can't open object */ +hid_t H5E_CANTCLOSEOBJ_g = FAIL; /* Can't close object */ +hid_t H5E_COMPLEN_g = FAIL; /* Name component is too long */ +hid_t H5E_PATH_g = FAIL; /* Problem with path to object */ + +/* Plugin errors */ +hid_t H5E_OPENERROR_g = FAIL; /* Can't open directory or file */ + +/* File accessibility errors */ +hid_t H5E_FILEEXISTS_g = FAIL; /* File already exists */ +hid_t H5E_FILEOPEN_g = FAIL; /* File already open */ +hid_t H5E_CANTCREATE_g = FAIL; /* Unable to create file */ +hid_t H5E_CANTOPENFILE_g = FAIL; /* Unable to open file */ +hid_t H5E_CANTCLOSEFILE_g = FAIL; /* Unable to close file */ +hid_t H5E_NOTHDF5_g = FAIL; /* Not an HDF5 file */ +hid_t H5E_BADFILE_g = FAIL; /* Bad file ID accessed */ +hid_t H5E_TRUNCATED_g = FAIL; /* File has been truncated */ +hid_t H5E_MOUNT_g = FAIL; /* File mount error */ + +/* Dataspace errors */ +hid_t H5E_CANTCLIP_g = FAIL; /* Can't clip hyperslab region */ +hid_t H5E_CANTCOUNT_g = FAIL; /* Can't count elements */ +hid_t H5E_CANTSELECT_g = FAIL; /* Can't select hyperslab */ +hid_t H5E_CANTNEXT_g = FAIL; /* Can't move to next iterator location */ +hid_t H5E_BADSELECT_g = FAIL; /* Invalid selection */ +hid_t H5E_CANTCOMPARE_g = FAIL; /* Can't compare objects */ /* Cache related errors */ hid_t H5E_CANTFLUSH_g = FAIL; /* Unable to flush data from cache */ @@ -78,28 +134,33 @@ hid_t H5E_CANTDIRTY_g = FAIL; /* Unable to mark metadata as dirty */ hid_t H5E_CANTEXPUNGE_g = FAIL; /* Unable to expunge a metadata cache entry */ hid_t H5E_CANTRESIZE_g = FAIL; /* Unable to resize a metadata cache entry */ +/* Free space errors */ +hid_t H5E_CANTMERGE_g = FAIL; /* Can't merge objects */ +hid_t H5E_CANTREVIVE_g = FAIL; /* Can't revive object */ +hid_t H5E_CANTSHRINK_g = FAIL; /* Can't shrink container */ + /* Datatype conversion errors */ hid_t H5E_CANTCONVERT_g = FAIL; /* Can't convert datatypes */ hid_t H5E_BADSIZE_g = FAIL; /* Bad size for object */ -/* Argument errors */ -hid_t H5E_UNINITIALIZED_g = FAIL; /* Information is uinitialized */ -hid_t H5E_UNSUPPORTED_g = FAIL; /* Feature is unsupported */ -hid_t H5E_BADTYPE_g = FAIL; /* Inappropriate type */ -hid_t H5E_BADRANGE_g = FAIL; /* Out of range */ -hid_t H5E_BADVALUE_g = FAIL; /* Bad value */ +/* Parallel MPI errors */ +hid_t H5E_MPI_g = FAIL; /* Some MPI function failed */ +hid_t H5E_MPIERRSTR_g = FAIL; /* MPI Error String */ +hid_t H5E_CANTRECV_g = FAIL; /* Can't receive data */ -/* Resource errors */ -hid_t H5E_NOSPACE_g = FAIL; /* No space available for allocation */ -hid_t H5E_CANTALLOC_g = FAIL; /* Can't allocate space */ -hid_t H5E_CANTCOPY_g = FAIL; /* Unable to copy object */ -hid_t H5E_CANTFREE_g = FAIL; /* Unable to free object */ -hid_t H5E_ALREADYEXISTS_g = FAIL; /* Object already exists */ -hid_t H5E_CANTLOCK_g = FAIL; /* Unable to lock object */ -hid_t H5E_CANTUNLOCK_g = FAIL; /* Unable to unlock object */ -hid_t H5E_CANTGC_g = FAIL; /* Unable to garbage collect */ -hid_t H5E_CANTGETSIZE_g = FAIL; /* Unable to compute size */ -hid_t H5E_OBJOPEN_g = FAIL; /* Object is already open */ +/* Property list errors */ +hid_t H5E_CANTGET_g = FAIL; /* Can't get value */ +hid_t H5E_CANTSET_g = FAIL; /* Can't set value */ +hid_t H5E_DUPCLASS_g = FAIL; /* Duplicate class name in parent class */ +hid_t H5E_SETDISALLOWED_g = FAIL; /* Disallowed operation */ + +/* Generic low-level file I/O errors */ +hid_t H5E_SEEKERROR_g = FAIL; /* Seek failed */ +hid_t H5E_READERROR_g = FAIL; /* Read failed */ +hid_t H5E_WRITEERROR_g = FAIL; /* Write failed */ +hid_t H5E_CLOSEERROR_g = FAIL; /* Close failed */ +hid_t H5E_OVERFLOW_g = FAIL; /* Address overflowed */ +hid_t H5E_FCNTL_g = FAIL; /* File control (fcntl) failed */ /* Object header related errors */ hid_t H5E_LINKCOUNT_g = FAIL; /* Bad object header link count */ @@ -112,41 +173,6 @@ hid_t H5E_CANTPACK_g = FAIL; /* Can't pack messages */ hid_t H5E_CANTRESET_g = FAIL; /* Can't reset object */ hid_t H5E_CANTRENAME_g = FAIL; /* Unable to rename object */ -/* Generic low-level file I/O errors */ -hid_t H5E_SEEKERROR_g = FAIL; /* Seek failed */ -hid_t H5E_READERROR_g = FAIL; /* Read failed */ -hid_t H5E_WRITEERROR_g = FAIL; /* Write failed */ -hid_t H5E_CLOSEERROR_g = FAIL; /* Close failed */ -hid_t H5E_OVERFLOW_g = FAIL; /* Address overflowed */ -hid_t H5E_FCNTL_g = FAIL; /* File control (fcntl) failed */ - -/* File accessibility errors */ -hid_t H5E_FILEEXISTS_g = FAIL; /* File already exists */ -hid_t H5E_FILEOPEN_g = FAIL; /* File already open */ -hid_t H5E_CANTCREATE_g = FAIL; /* Unable to create file */ -hid_t H5E_CANTOPENFILE_g = FAIL; /* Unable to open file */ -hid_t H5E_CANTCLOSEFILE_g = FAIL; /* Unable to close file */ -hid_t H5E_NOTHDF5_g = FAIL; /* Not an HDF5 file */ -hid_t H5E_BADFILE_g = FAIL; /* Bad file ID accessed */ -hid_t H5E_TRUNCATED_g = FAIL; /* File has been truncated */ -hid_t H5E_MOUNT_g = FAIL; /* File mount error */ - -/* No error */ -hid_t H5E_NONE_MINOR_g = FAIL; /* No error */ - -/* Heap errors */ -hid_t H5E_CANTRESTORE_g = FAIL; /* Can't restore condition */ -hid_t H5E_CANTCOMPUTE_g = FAIL; /* Can't compute value */ -hid_t H5E_CANTEXTEND_g = FAIL; /* Can't extend heap's space */ -hid_t H5E_CANTATTACH_g = FAIL; /* Can't attach object */ -hid_t H5E_CANTUPDATE_g = FAIL; /* Can't update object */ -hid_t H5E_CANTOPERATE_g = FAIL; /* Can't operate on object */ - -/* Function entry/exit interface errors */ -hid_t H5E_CANTINIT_g = FAIL; /* Unable to initialize object */ -hid_t H5E_ALREADYINIT_g = FAIL; /* Object already initialized */ -hid_t H5E_CANTRELEASE_g = FAIL; /* Unable to release object */ - /* B-tree related errors */ hid_t H5E_NOTFOUND_g = FAIL; /* Object not found */ hid_t H5E_EXISTS_g = FAIL; /* Object already exists */ @@ -160,55 +186,29 @@ hid_t H5E_CANTLIST_g = FAIL; /* Unable to list node */ hid_t H5E_CANTMODIFY_g = FAIL; /* Unable to modify record */ hid_t H5E_CANTREMOVE_g = FAIL; /* Unable to remove object */ -/* Group related errors */ -hid_t H5E_CANTOPENOBJ_g = FAIL; /* Can't open object */ -hid_t H5E_CANTCLOSEOBJ_g = FAIL; /* Can't close object */ -hid_t H5E_COMPLEN_g = FAIL; /* Name component is too long */ -hid_t H5E_PATH_g = FAIL; /* Problem with path to object */ - -/* Parallel MPI errors */ -hid_t H5E_MPI_g = FAIL; /* Some MPI function failed */ -hid_t H5E_MPIERRSTR_g = FAIL; /* MPI Error String */ -hid_t H5E_CANTRECV_g = FAIL; /* Can't receive data */ - -/* System level errors */ -hid_t H5E_SYSERRSTR_g = FAIL; /* System error message */ - -/* Link related errors */ -hid_t H5E_TRAVERSE_g = FAIL; /* Link traversal failure */ -hid_t H5E_NLINKS_g = FAIL; /* Too many soft links in path */ -hid_t H5E_NOTREGISTERED_g = FAIL; /* Link class not registered */ -hid_t H5E_CANTMOVE_g = FAIL; /* Can't move object */ -hid_t H5E_CANTSORT_g = FAIL; /* Can't sort objects */ - -/* I/O pipeline errors */ -hid_t H5E_NOFILTER_g = FAIL; /* Requested filter is not available */ -hid_t H5E_CALLBACK_g = FAIL; /* Callback failed */ -hid_t H5E_CANAPPLY_g = FAIL; /* Error from filter 'can apply' callback */ -hid_t H5E_SETLOCAL_g = FAIL; /* Error from filter 'set local' callback */ -hid_t H5E_NOENCODER_g = FAIL; /* Filter present but encoding disabled */ -hid_t H5E_CANTFILTER_g = FAIL; /* Filter operation failed */ - -/* Property list errors */ -hid_t H5E_CANTGET_g = FAIL; /* Can't get value */ -hid_t H5E_CANTSET_g = FAIL; /* Can't set value */ -hid_t H5E_DUPCLASS_g = FAIL; /* Duplicate class name in parent class */ -hid_t H5E_SETDISALLOWED_g = FAIL; /* Disallowed operation */ - -/* Free space errors */ -hid_t H5E_CANTMERGE_g = FAIL; /* Can't merge objects */ -hid_t H5E_CANTREVIVE_g = FAIL; /* Can't revive object */ -hid_t H5E_CANTSHRINK_g = FAIL; /* Can't shrink container */ +/* Resource errors */ +hid_t H5E_NOSPACE_g = FAIL; /* No space available for allocation */ +hid_t H5E_CANTALLOC_g = FAIL; /* Can't allocate space */ +hid_t H5E_CANTCOPY_g = FAIL; /* Unable to copy object */ +hid_t H5E_CANTFREE_g = FAIL; /* Unable to free object */ +hid_t H5E_ALREADYEXISTS_g = FAIL; /* Object already exists */ +hid_t H5E_CANTLOCK_g = FAIL; /* Unable to lock object */ +hid_t H5E_CANTUNLOCK_g = FAIL; /* Unable to unlock object */ +hid_t H5E_CANTGC_g = FAIL; /* Unable to garbage collect */ +hid_t H5E_CANTGETSIZE_g = FAIL; /* Unable to compute size */ +hid_t H5E_OBJOPEN_g = FAIL; /* Object is already open */ -/* Dataspace errors */ -hid_t H5E_CANTCLIP_g = FAIL; /* Can't clip hyperslab region */ -hid_t H5E_CANTCOUNT_g = FAIL; /* Can't count elements */ -hid_t H5E_CANTSELECT_g = FAIL; /* Can't select hyperslab */ -hid_t H5E_CANTNEXT_g = FAIL; /* Can't move to next iterator location */ -hid_t H5E_BADSELECT_g = FAIL; /* Invalid selection */ -hid_t H5E_CANTCOMPARE_g = FAIL; /* Can't compare objects */ +/* Object atom related errors */ +hid_t H5E_BADATOM_g = FAIL; /* Unable to find atom information (already closed?) */ +hid_t H5E_BADGROUP_g = FAIL; /* Unable to find ID group information */ +hid_t H5E_CANTREGISTER_g = FAIL; /* Unable to register new atom */ +hid_t H5E_CANTINC_g = FAIL; /* Unable to increment reference count */ +hid_t H5E_CANTDEC_g = FAIL; /* Unable to decrement reference count */ +hid_t H5E_NOIDS_g = FAIL; /* Out of IDs for group */ -/* Plugin errors */ -hid_t H5E_OPENERROR_g = FAIL; /* Can't open directory or file */ +/* Function entry/exit interface errors */ +hid_t H5E_CANTINIT_g = FAIL; /* Unable to initialize object */ +hid_t H5E_ALREADYINIT_g = FAIL; /* Object already initialized */ +hid_t H5E_CANTRELEASE_g = FAIL; /* Unable to release object */ #endif /* H5Edefin_H */ diff --git a/src/H5Einit.h b/src/H5Einit.h index fcb58c4..ca149cd 100644 --- a/src/H5Einit.h +++ b/src/H5Einit.h @@ -22,55 +22,105 @@ /* Major error codes */ /*********************/ -HDassert(H5E_LINK_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Links"))==NULL) +HDassert(H5E_SYM_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Symbol table"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_LINK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_SYM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_FILE_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "File accessibility"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_FILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_INTERNAL_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Internal error (too specific to document in detail)"))==NULL) +HDassert(H5E_DATATYPE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Datatype"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_INTERNAL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_DATATYPE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ARGS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Invalid arguments to routine"))==NULL) +HDassert(H5E_LINK_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Links"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ARGS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_LINK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_DATASPACE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Dataspace"))==NULL) +HDassert(H5E_DATASET_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Dataset"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_DATASPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_DATASET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_SYM_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Symbol table"))==NULL) +HDassert(H5E_ATOM_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Object atom"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SYM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ATOM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_RESOURCE_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "Resource unavailable"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_RESOURCE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_INTERNAL_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Internal error (too specific to document in detail)"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_INTERNAL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CACHE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Object cache"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CACHE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_SOHM_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Shared Object Header Messages"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_SOHM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_FUNC_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Function entry/exit"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_FUNC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_RS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Reference Counted Strings"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_RS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_PLIST_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Property lists"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_PLIST_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_BTREE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "B-Tree node"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_BTREE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_NONE_MAJOR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "No error"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_NONE_MAJOR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_SLIST_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "Skip Lists"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_SLIST_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_DATASET_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Dataset"))==NULL) +HDassert(H5E_DATASPACE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Dataspace"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_DATASET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_DATASPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_STORAGE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Data storage"))==NULL) +HDassert(H5E_ARGS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Invalid arguments to routine"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_STORAGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ARGS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_REFERENCE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "References"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_REFERENCE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_FSPACE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Free Space Manager"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_FSPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_EFL_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "External file list"))==NULL) @@ -82,25 +132,25 @@ if((msg = H5E_create_msg(cls, H5E_MAJOR, "Data filters"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_PLINE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_DATATYPE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Datatype"))==NULL) +HDassert(H5E_ERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Error API"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_DATATYPE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ATOM_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Object atom"))==NULL) +HDassert(H5E_ATTR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Attribute"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ATOM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ATTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CACHE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Object cache"))==NULL) +HDassert(H5E_HEAP_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Heap"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CACHE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_HEAP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Error API"))==NULL) +HDassert(H5E_VFL_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Virtual File Layer"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_VFL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_OHDR_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "Object header"))==NULL) @@ -112,107 +162,265 @@ if((msg = H5E_create_msg(cls, H5E_MAJOR, "Low-level I/O"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_IO_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_SOHM_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Shared Object Header Messages"))==NULL) +HDassert(H5E_TST_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Ternary Search Trees"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SOHM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_TST_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_RS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Reference Counted Strings"))==NULL) +HDassert(H5E_STORAGE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MAJOR, "Data storage"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_RS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_STORAGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") HDassert(H5E_PLUGIN_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MAJOR, "Plugin for dynamically loaded library"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") if((H5E_PLUGIN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_TST_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Ternary Search Trees"))==NULL) + +/*********************/ +/* Minor error codes */ +/*********************/ + + +/* Heap errors */ +HDassert(H5E_CANTRESTORE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't restore condition"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_TST_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTRESTORE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_FSPACE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Free Space Manager"))==NULL) +HDassert(H5E_CANTCOMPUTE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't compute value"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_FSPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTCOMPUTE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BTREE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "B-Tree node"))==NULL) +HDassert(H5E_CANTEXTEND_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't extend heap's space"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BTREE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTEXTEND_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_REFERENCE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "References"))==NULL) +HDassert(H5E_CANTATTACH_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't attach object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_REFERENCE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTATTACH_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_FUNC_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Function entry/exit"))==NULL) +HDassert(H5E_CANTUPDATE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't update object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_FUNC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTUPDATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_VFL_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Virtual File Layer"))==NULL) +HDassert(H5E_CANTOPERATE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't operate on object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_VFL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTOPERATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_PLIST_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Property lists"))==NULL) + +/* No error */ +HDassert(H5E_NONE_MINOR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "No error"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_PLIST_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_NONE_MINOR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_HEAP_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Heap"))==NULL) + +/* Link related errors */ +HDassert(H5E_TRAVERSE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Link traversal failure"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_HEAP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_TRAVERSE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NONE_MAJOR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "No error"))==NULL) +HDassert(H5E_NLINKS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Too many soft links in path"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NONE_MAJOR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_NLINKS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ATTR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MAJOR, "Attribute"))==NULL) +HDassert(H5E_NOTREGISTERED_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Link class not registered"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ATTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_NOTREGISTERED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTMOVE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't move object"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTMOVE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTSORT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't sort objects"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTSORT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/*********************/ -/* Minor error codes */ -/*********************/ +/* I/O pipeline errors */ +HDassert(H5E_NOFILTER_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Requested filter is not available"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_NOFILTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CALLBACK_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Callback failed"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CALLBACK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANAPPLY_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Error from filter 'can apply' callback"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANAPPLY_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_SETLOCAL_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Error from filter 'set local' callback"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_SETLOCAL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_NOENCODER_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Filter present but encoding disabled"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_NOENCODER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTFILTER_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Filter operation failed"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTFILTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +/* System level errors */ +HDassert(H5E_SYSERRSTR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "System error message"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_SYSERRSTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Object atom related errors */ -HDassert(H5E_BADATOM_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to find atom information (already closed?)"))==NULL) +/* Argument errors */ +HDassert(H5E_UNINITIALIZED_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Information is uinitialized"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADATOM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_UNINITIALIZED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADGROUP_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to find ID group information"))==NULL) +HDassert(H5E_UNSUPPORTED_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Feature is unsupported"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADGROUP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_UNSUPPORTED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTREGISTER_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to register new atom"))==NULL) +HDassert(H5E_BADTYPE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Inappropriate type"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTREGISTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_BADTYPE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTINC_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to increment reference count"))==NULL) +HDassert(H5E_BADRANGE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Out of range"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTINC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_BADRANGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTDEC_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to decrement reference count"))==NULL) +HDassert(H5E_BADVALUE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Bad value"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTDEC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_BADVALUE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NOIDS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Out of IDs for group"))==NULL) + +/* Group related errors */ +HDassert(H5E_CANTOPENOBJ_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't open object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOIDS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTOPENOBJ_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTCLOSEOBJ_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't close object"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCLOSEOBJ_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_COMPLEN_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Name component is too long"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_COMPLEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_PATH_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Problem with path to object"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_PATH_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") + +/* Plugin errors */ +HDassert(H5E_OPENERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't open directory or file"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_OPENERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") + +/* File accessibility errors */ +HDassert(H5E_FILEEXISTS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "File already exists"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_FILEEXISTS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_FILEOPEN_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "File already open"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_FILEOPEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTCREATE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to create file"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCREATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTOPENFILE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to open file"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTOPENFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTCLOSEFILE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to close file"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCLOSEFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_NOTHDF5_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Not an HDF5 file"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_NOTHDF5_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_BADFILE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Bad file ID accessed"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_BADFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_TRUNCATED_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "File has been truncated"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_TRUNCATED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_MOUNT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "File mount error"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_MOUNT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") + +/* Dataspace errors */ +HDassert(H5E_CANTCLIP_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't clip hyperslab region"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCLIP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTCOUNT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't count elements"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCOUNT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTSELECT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't select hyperslab"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTSELECT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTNEXT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't move to next iterator location"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTNEXT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_BADSELECT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Invalid selection"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_BADSELECT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTCOMPARE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't compare objects"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTCOMPARE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") /* Cache related errors */ @@ -292,6 +500,23 @@ if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to resize a metadata cache entr if((H5E_CANTRESIZE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +/* Free space errors */ +HDassert(H5E_CANTMERGE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't merge objects"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTMERGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTREVIVE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't revive object"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTREVIVE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") +HDassert(H5E_CANTSHRINK_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't shrink container"))==NULL) + HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") +if((H5E_CANTSHRINK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) + HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") + /* Datatype conversion errors */ HDassert(H5E_CANTCONVERT_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't convert datatypes"))==NULL) @@ -304,83 +529,75 @@ if((msg = H5E_create_msg(cls, H5E_MINOR, "Bad size for object"))==NULL) if((H5E_BADSIZE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Argument errors */ -HDassert(H5E_UNINITIALIZED_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Information is uinitialized"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_UNINITIALIZED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_UNSUPPORTED_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Feature is unsupported"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_UNSUPPORTED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADTYPE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Inappropriate type"))==NULL) +/* Parallel MPI errors */ +HDassert(H5E_MPI_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Some MPI function failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADTYPE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_MPI_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADRANGE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Out of range"))==NULL) +HDassert(H5E_MPIERRSTR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "MPI Error String"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADRANGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_MPIERRSTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADVALUE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Bad value"))==NULL) +HDassert(H5E_CANTRECV_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't receive data"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADVALUE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTRECV_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Resource errors */ -HDassert(H5E_NOSPACE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "No space available for allocation"))==NULL) +/* Property list errors */ +HDassert(H5E_CANTGET_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't get value"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOSPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTGET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTALLOC_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't allocate space"))==NULL) +HDassert(H5E_CANTSET_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't set value"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTALLOC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTSET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCOPY_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to copy object"))==NULL) +HDassert(H5E_DUPCLASS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Duplicate class name in parent class"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCOPY_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_DUPCLASS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTFREE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to free object"))==NULL) +HDassert(H5E_SETDISALLOWED_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Disallowed operation"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTFREE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_SETDISALLOWED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ALREADYEXISTS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Object already exists"))==NULL) + +/* Generic low-level file I/O errors */ +HDassert(H5E_SEEKERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Seek failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ALREADYEXISTS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_SEEKERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTLOCK_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to lock object"))==NULL) +HDassert(H5E_READERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Read failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTLOCK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_READERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTUNLOCK_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to unlock object"))==NULL) +HDassert(H5E_WRITEERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Write failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTUNLOCK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_WRITEERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTGC_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to garbage collect"))==NULL) +HDassert(H5E_CLOSEERROR_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Close failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTGC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CLOSEERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTGETSIZE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to compute size"))==NULL) +HDassert(H5E_OVERFLOW_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Address overflowed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTGETSIZE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_OVERFLOW_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_OBJOPEN_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Object is already open"))==NULL) +HDassert(H5E_FCNTL_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "File control (fcntl) failed"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_OBJOPEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_FCNTL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") /* Object header related errors */ @@ -430,141 +647,6 @@ if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to rename object"))==NULL) if((H5E_CANTRENAME_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Generic low-level file I/O errors */ -HDassert(H5E_SEEKERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Seek failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SEEKERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_READERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Read failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_READERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_WRITEERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Write failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_WRITEERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CLOSEERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Close failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CLOSEERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_OVERFLOW_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Address overflowed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_OVERFLOW_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_FCNTL_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "File control (fcntl) failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_FCNTL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* File accessibility errors */ -HDassert(H5E_FILEEXISTS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "File already exists"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_FILEEXISTS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_FILEOPEN_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "File already open"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_FILEOPEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCREATE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to create file"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCREATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTOPENFILE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to open file"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTOPENFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCLOSEFILE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to close file"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCLOSEFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NOTHDF5_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Not an HDF5 file"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOTHDF5_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADFILE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Bad file ID accessed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADFILE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_TRUNCATED_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "File has been truncated"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_TRUNCATED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_MOUNT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "File mount error"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_MOUNT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* No error */ -HDassert(H5E_NONE_MINOR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "No error"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NONE_MINOR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Heap errors */ -HDassert(H5E_CANTRESTORE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't restore condition"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTRESTORE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCOMPUTE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't compute value"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCOMPUTE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTEXTEND_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't extend heap's space"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTEXTEND_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTATTACH_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't attach object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTATTACH_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTUPDATE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't update object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTUPDATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTOPERATE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't operate on object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTOPERATE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Function entry/exit interface errors */ -HDassert(H5E_CANTINIT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to initialize object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTINIT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_ALREADYINIT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Object already initialized"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_ALREADYINIT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTRELEASE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to release object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTRELEASE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - /* B-tree related errors */ HDassert(H5E_NOTFOUND_g==(-1)); if((msg = H5E_create_msg(cls, H5E_MINOR, "Object not found"))==NULL) @@ -622,187 +704,105 @@ if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to remove object"))==NULL) if((H5E_CANTREMOVE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Group related errors */ -HDassert(H5E_CANTOPENOBJ_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't open object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTOPENOBJ_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCLOSEOBJ_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't close object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCLOSEOBJ_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_COMPLEN_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Name component is too long"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_COMPLEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_PATH_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Problem with path to object"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_PATH_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Parallel MPI errors */ -HDassert(H5E_MPI_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Some MPI function failed"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_MPI_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_MPIERRSTR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "MPI Error String"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_MPIERRSTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTRECV_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't receive data"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTRECV_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* System level errors */ -HDassert(H5E_SYSERRSTR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "System error message"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SYSERRSTR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Link related errors */ -HDassert(H5E_TRAVERSE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Link traversal failure"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_TRAVERSE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NLINKS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Too many soft links in path"))==NULL) +/* Resource errors */ +HDassert(H5E_NOSPACE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "No space available for allocation"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NLINKS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_NOSPACE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NOTREGISTERED_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Link class not registered"))==NULL) +HDassert(H5E_CANTALLOC_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't allocate space"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOTREGISTERED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTALLOC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTMOVE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't move object"))==NULL) +HDassert(H5E_CANTCOPY_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to copy object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTMOVE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTCOPY_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTSORT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't sort objects"))==NULL) +HDassert(H5E_CANTFREE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to free object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTSORT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTFREE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* I/O pipeline errors */ -HDassert(H5E_NOFILTER_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Requested filter is not available"))==NULL) +HDassert(H5E_ALREADYEXISTS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Object already exists"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOFILTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ALREADYEXISTS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CALLBACK_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Callback failed"))==NULL) +HDassert(H5E_CANTLOCK_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to lock object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CALLBACK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTLOCK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANAPPLY_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Error from filter 'can apply' callback"))==NULL) +HDassert(H5E_CANTUNLOCK_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to unlock object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANAPPLY_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTUNLOCK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_SETLOCAL_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Error from filter 'set local' callback"))==NULL) +HDassert(H5E_CANTGC_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to garbage collect"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SETLOCAL_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTGC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_NOENCODER_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Filter present but encoding disabled"))==NULL) +HDassert(H5E_CANTGETSIZE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to compute size"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_NOENCODER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTGETSIZE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTFILTER_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Filter operation failed"))==NULL) +HDassert(H5E_OBJOPEN_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Object is already open"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTFILTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_OBJOPEN_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Property list errors */ -HDassert(H5E_CANTGET_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't get value"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTGET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTSET_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't set value"))==NULL) +/* Object atom related errors */ +HDassert(H5E_BADATOM_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to find atom information (already closed?)"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTSET_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_BADATOM_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_DUPCLASS_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Duplicate class name in parent class"))==NULL) +HDassert(H5E_BADGROUP_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to find ID group information"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_DUPCLASS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_BADGROUP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_SETDISALLOWED_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Disallowed operation"))==NULL) +HDassert(H5E_CANTREGISTER_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to register new atom"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_SETDISALLOWED_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTREGISTER_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Free space errors */ -HDassert(H5E_CANTMERGE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't merge objects"))==NULL) +HDassert(H5E_CANTINC_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to increment reference count"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTMERGE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTINC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTREVIVE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't revive object"))==NULL) +HDassert(H5E_CANTDEC_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to decrement reference count"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTREVIVE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTDEC_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTSHRINK_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't shrink container"))==NULL) +HDassert(H5E_NOIDS_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Out of IDs for group"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTSHRINK_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_NOIDS_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -/* Dataspace errors */ -HDassert(H5E_CANTCLIP_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't clip hyperslab region"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCLIP_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCOUNT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't count elements"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCOUNT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTSELECT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't select hyperslab"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTSELECT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTNEXT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't move to next iterator location"))==NULL) - HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTNEXT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) - HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_BADSELECT_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Invalid selection"))==NULL) +/* Function entry/exit interface errors */ +HDassert(H5E_CANTINIT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to initialize object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_BADSELECT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTINIT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") -HDassert(H5E_CANTCOMPARE_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't compare objects"))==NULL) +HDassert(H5E_ALREADYINIT_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Object already initialized"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_CANTCOMPARE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_ALREADYINIT_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") - -/* Plugin errors */ -HDassert(H5E_OPENERROR_g==(-1)); -if((msg = H5E_create_msg(cls, H5E_MINOR, "Can't open directory or file"))==NULL) +HDassert(H5E_CANTRELEASE_g==(-1)); +if((msg = H5E_create_msg(cls, H5E_MINOR, "Unable to release object"))==NULL) HGOTO_ERROR(H5E_ERROR, H5E_CANTINIT, FAIL, "error message initialization failed") -if((H5E_OPENERROR_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) +if((H5E_CANTRELEASE_g = H5I_register(H5I_ERROR_MSG, msg, FALSE))<0) HGOTO_ERROR(H5E_ERROR, H5E_CANTREGISTER, FAIL, "can't register error message") #endif /* H5Einit_H */ diff --git a/src/H5Epubgen.h b/src/H5Epubgen.h index b47191c..986d805 100644 --- a/src/H5Epubgen.h +++ b/src/H5Epubgen.h @@ -26,86 +26,180 @@ extern "C" { /* Major error codes */ /*********************/ -#define H5E_LINK (H5OPEN H5E_LINK_g) -#define H5E_FILE (H5OPEN H5E_FILE_g) -#define H5E_INTERNAL (H5OPEN H5E_INTERNAL_g) -#define H5E_ARGS (H5OPEN H5E_ARGS_g) -#define H5E_DATASPACE (H5OPEN H5E_DATASPACE_g) #define H5E_SYM (H5OPEN H5E_SYM_g) -#define H5E_RESOURCE (H5OPEN H5E_RESOURCE_g) -#define H5E_SLIST (H5OPEN H5E_SLIST_g) -#define H5E_DATASET (H5OPEN H5E_DATASET_g) -#define H5E_STORAGE (H5OPEN H5E_STORAGE_g) -#define H5E_EFL (H5OPEN H5E_EFL_g) -#define H5E_PLINE (H5OPEN H5E_PLINE_g) +#define H5E_FILE (H5OPEN H5E_FILE_g) #define H5E_DATATYPE (H5OPEN H5E_DATATYPE_g) +#define H5E_LINK (H5OPEN H5E_LINK_g) +#define H5E_DATASET (H5OPEN H5E_DATASET_g) #define H5E_ATOM (H5OPEN H5E_ATOM_g) +#define H5E_RESOURCE (H5OPEN H5E_RESOURCE_g) +#define H5E_INTERNAL (H5OPEN H5E_INTERNAL_g) #define H5E_CACHE (H5OPEN H5E_CACHE_g) -#define H5E_ERROR (H5OPEN H5E_ERROR_g) -#define H5E_OHDR (H5OPEN H5E_OHDR_g) -#define H5E_IO (H5OPEN H5E_IO_g) #define H5E_SOHM (H5OPEN H5E_SOHM_g) -#define H5E_RS (H5OPEN H5E_RS_g) -#define H5E_PLUGIN (H5OPEN H5E_PLUGIN_g) -#define H5E_TST (H5OPEN H5E_TST_g) -#define H5E_FSPACE (H5OPEN H5E_FSPACE_g) -#define H5E_BTREE (H5OPEN H5E_BTREE_g) -#define H5E_REFERENCE (H5OPEN H5E_REFERENCE_g) #define H5E_FUNC (H5OPEN H5E_FUNC_g) -#define H5E_VFL (H5OPEN H5E_VFL_g) +#define H5E_RS (H5OPEN H5E_RS_g) #define H5E_PLIST (H5OPEN H5E_PLIST_g) -#define H5E_HEAP (H5OPEN H5E_HEAP_g) +#define H5E_BTREE (H5OPEN H5E_BTREE_g) #define H5E_NONE_MAJOR (H5OPEN H5E_NONE_MAJOR_g) +#define H5E_SLIST (H5OPEN H5E_SLIST_g) +#define H5E_DATASPACE (H5OPEN H5E_DATASPACE_g) +#define H5E_ARGS (H5OPEN H5E_ARGS_g) +#define H5E_REFERENCE (H5OPEN H5E_REFERENCE_g) +#define H5E_FSPACE (H5OPEN H5E_FSPACE_g) +#define H5E_EFL (H5OPEN H5E_EFL_g) +#define H5E_PLINE (H5OPEN H5E_PLINE_g) +#define H5E_ERROR (H5OPEN H5E_ERROR_g) #define H5E_ATTR (H5OPEN H5E_ATTR_g) -H5_DLLVAR hid_t H5E_LINK_g; /* Links */ -H5_DLLVAR hid_t H5E_FILE_g; /* File accessibility */ -H5_DLLVAR hid_t H5E_INTERNAL_g; /* Internal error (too specific to document in detail) */ -H5_DLLVAR hid_t H5E_ARGS_g; /* Invalid arguments to routine */ -H5_DLLVAR hid_t H5E_DATASPACE_g; /* Dataspace */ +#define H5E_HEAP (H5OPEN H5E_HEAP_g) +#define H5E_VFL (H5OPEN H5E_VFL_g) +#define H5E_OHDR (H5OPEN H5E_OHDR_g) +#define H5E_IO (H5OPEN H5E_IO_g) +#define H5E_TST (H5OPEN H5E_TST_g) +#define H5E_STORAGE (H5OPEN H5E_STORAGE_g) +#define H5E_PLUGIN (H5OPEN H5E_PLUGIN_g) H5_DLLVAR hid_t H5E_SYM_g; /* Symbol table */ -H5_DLLVAR hid_t H5E_RESOURCE_g; /* Resource unavailable */ -H5_DLLVAR hid_t H5E_SLIST_g; /* Skip Lists */ -H5_DLLVAR hid_t H5E_DATASET_g; /* Dataset */ -H5_DLLVAR hid_t H5E_STORAGE_g; /* Data storage */ -H5_DLLVAR hid_t H5E_EFL_g; /* External file list */ -H5_DLLVAR hid_t H5E_PLINE_g; /* Data filters */ +H5_DLLVAR hid_t H5E_FILE_g; /* File accessibility */ H5_DLLVAR hid_t H5E_DATATYPE_g; /* Datatype */ +H5_DLLVAR hid_t H5E_LINK_g; /* Links */ +H5_DLLVAR hid_t H5E_DATASET_g; /* Dataset */ H5_DLLVAR hid_t H5E_ATOM_g; /* Object atom */ +H5_DLLVAR hid_t H5E_RESOURCE_g; /* Resource unavailable */ +H5_DLLVAR hid_t H5E_INTERNAL_g; /* Internal error (too specific to document in detail) */ H5_DLLVAR hid_t H5E_CACHE_g; /* Object cache */ -H5_DLLVAR hid_t H5E_ERROR_g; /* Error API */ -H5_DLLVAR hid_t H5E_OHDR_g; /* Object header */ -H5_DLLVAR hid_t H5E_IO_g; /* Low-level I/O */ H5_DLLVAR hid_t H5E_SOHM_g; /* Shared Object Header Messages */ -H5_DLLVAR hid_t H5E_RS_g; /* Reference Counted Strings */ -H5_DLLVAR hid_t H5E_PLUGIN_g; /* Plugin for dynamically loaded library */ -H5_DLLVAR hid_t H5E_TST_g; /* Ternary Search Trees */ -H5_DLLVAR hid_t H5E_FSPACE_g; /* Free Space Manager */ -H5_DLLVAR hid_t H5E_BTREE_g; /* B-Tree node */ -H5_DLLVAR hid_t H5E_REFERENCE_g; /* References */ H5_DLLVAR hid_t H5E_FUNC_g; /* Function entry/exit */ -H5_DLLVAR hid_t H5E_VFL_g; /* Virtual File Layer */ +H5_DLLVAR hid_t H5E_RS_g; /* Reference Counted Strings */ H5_DLLVAR hid_t H5E_PLIST_g; /* Property lists */ -H5_DLLVAR hid_t H5E_HEAP_g; /* Heap */ +H5_DLLVAR hid_t H5E_BTREE_g; /* B-Tree node */ H5_DLLVAR hid_t H5E_NONE_MAJOR_g; /* No error */ +H5_DLLVAR hid_t H5E_SLIST_g; /* Skip Lists */ +H5_DLLVAR hid_t H5E_DATASPACE_g; /* Dataspace */ +H5_DLLVAR hid_t H5E_ARGS_g; /* Invalid arguments to routine */ +H5_DLLVAR hid_t H5E_REFERENCE_g; /* References */ +H5_DLLVAR hid_t H5E_FSPACE_g; /* Free Space Manager */ +H5_DLLVAR hid_t H5E_EFL_g; /* External file list */ +H5_DLLVAR hid_t H5E_PLINE_g; /* Data filters */ +H5_DLLVAR hid_t H5E_ERROR_g; /* Error API */ H5_DLLVAR hid_t H5E_ATTR_g; /* Attribute */ +H5_DLLVAR hid_t H5E_HEAP_g; /* Heap */ +H5_DLLVAR hid_t H5E_VFL_g; /* Virtual File Layer */ +H5_DLLVAR hid_t H5E_OHDR_g; /* Object header */ +H5_DLLVAR hid_t H5E_IO_g; /* Low-level I/O */ +H5_DLLVAR hid_t H5E_TST_g; /* Ternary Search Trees */ +H5_DLLVAR hid_t H5E_STORAGE_g; /* Data storage */ +H5_DLLVAR hid_t H5E_PLUGIN_g; /* Plugin for dynamically loaded library */ /*********************/ /* Minor error codes */ /*********************/ -/* Object atom related errors */ -#define H5E_BADATOM (H5OPEN H5E_BADATOM_g) -#define H5E_BADGROUP (H5OPEN H5E_BADGROUP_g) -#define H5E_CANTREGISTER (H5OPEN H5E_CANTREGISTER_g) -#define H5E_CANTINC (H5OPEN H5E_CANTINC_g) -#define H5E_CANTDEC (H5OPEN H5E_CANTDEC_g) -#define H5E_NOIDS (H5OPEN H5E_NOIDS_g) -H5_DLLVAR hid_t H5E_BADATOM_g; /* Unable to find atom information (already closed?) */ -H5_DLLVAR hid_t H5E_BADGROUP_g; /* Unable to find ID group information */ -H5_DLLVAR hid_t H5E_CANTREGISTER_g; /* Unable to register new atom */ -H5_DLLVAR hid_t H5E_CANTINC_g; /* Unable to increment reference count */ -H5_DLLVAR hid_t H5E_CANTDEC_g; /* Unable to decrement reference count */ -H5_DLLVAR hid_t H5E_NOIDS_g; /* Out of IDs for group */ +/* Heap errors */ +#define H5E_CANTRESTORE (H5OPEN H5E_CANTRESTORE_g) +#define H5E_CANTCOMPUTE (H5OPEN H5E_CANTCOMPUTE_g) +#define H5E_CANTEXTEND (H5OPEN H5E_CANTEXTEND_g) +#define H5E_CANTATTACH (H5OPEN H5E_CANTATTACH_g) +#define H5E_CANTUPDATE (H5OPEN H5E_CANTUPDATE_g) +#define H5E_CANTOPERATE (H5OPEN H5E_CANTOPERATE_g) +H5_DLLVAR hid_t H5E_CANTRESTORE_g; /* Can't restore condition */ +H5_DLLVAR hid_t H5E_CANTCOMPUTE_g; /* Can't compute value */ +H5_DLLVAR hid_t H5E_CANTEXTEND_g; /* Can't extend heap's space */ +H5_DLLVAR hid_t H5E_CANTATTACH_g; /* Can't attach object */ +H5_DLLVAR hid_t H5E_CANTUPDATE_g; /* Can't update object */ +H5_DLLVAR hid_t H5E_CANTOPERATE_g; /* Can't operate on object */ + +/* No error */ +#define H5E_NONE_MINOR (H5OPEN H5E_NONE_MINOR_g) +H5_DLLVAR hid_t H5E_NONE_MINOR_g; /* No error */ + +/* Link related errors */ +#define H5E_TRAVERSE (H5OPEN H5E_TRAVERSE_g) +#define H5E_NLINKS (H5OPEN H5E_NLINKS_g) +#define H5E_NOTREGISTERED (H5OPEN H5E_NOTREGISTERED_g) +#define H5E_CANTMOVE (H5OPEN H5E_CANTMOVE_g) +#define H5E_CANTSORT (H5OPEN H5E_CANTSORT_g) +H5_DLLVAR hid_t H5E_TRAVERSE_g; /* Link traversal failure */ +H5_DLLVAR hid_t H5E_NLINKS_g; /* Too many soft links in path */ +H5_DLLVAR hid_t H5E_NOTREGISTERED_g; /* Link class not registered */ +H5_DLLVAR hid_t H5E_CANTMOVE_g; /* Can't move object */ +H5_DLLVAR hid_t H5E_CANTSORT_g; /* Can't sort objects */ + +/* I/O pipeline errors */ +#define H5E_NOFILTER (H5OPEN H5E_NOFILTER_g) +#define H5E_CALLBACK (H5OPEN H5E_CALLBACK_g) +#define H5E_CANAPPLY (H5OPEN H5E_CANAPPLY_g) +#define H5E_SETLOCAL (H5OPEN H5E_SETLOCAL_g) +#define H5E_NOENCODER (H5OPEN H5E_NOENCODER_g) +#define H5E_CANTFILTER (H5OPEN H5E_CANTFILTER_g) +H5_DLLVAR hid_t H5E_NOFILTER_g; /* Requested filter is not available */ +H5_DLLVAR hid_t H5E_CALLBACK_g; /* Callback failed */ +H5_DLLVAR hid_t H5E_CANAPPLY_g; /* Error from filter 'can apply' callback */ +H5_DLLVAR hid_t H5E_SETLOCAL_g; /* Error from filter 'set local' callback */ +H5_DLLVAR hid_t H5E_NOENCODER_g; /* Filter present but encoding disabled */ +H5_DLLVAR hid_t H5E_CANTFILTER_g; /* Filter operation failed */ + +/* System level errors */ +#define H5E_SYSERRSTR (H5OPEN H5E_SYSERRSTR_g) +H5_DLLVAR hid_t H5E_SYSERRSTR_g; /* System error message */ + +/* Argument errors */ +#define H5E_UNINITIALIZED (H5OPEN H5E_UNINITIALIZED_g) +#define H5E_UNSUPPORTED (H5OPEN H5E_UNSUPPORTED_g) +#define H5E_BADTYPE (H5OPEN H5E_BADTYPE_g) +#define H5E_BADRANGE (H5OPEN H5E_BADRANGE_g) +#define H5E_BADVALUE (H5OPEN H5E_BADVALUE_g) +H5_DLLVAR hid_t H5E_UNINITIALIZED_g; /* Information is uinitialized */ +H5_DLLVAR hid_t H5E_UNSUPPORTED_g; /* Feature is unsupported */ +H5_DLLVAR hid_t H5E_BADTYPE_g; /* Inappropriate type */ +H5_DLLVAR hid_t H5E_BADRANGE_g; /* Out of range */ +H5_DLLVAR hid_t H5E_BADVALUE_g; /* Bad value */ + +/* Group related errors */ +#define H5E_CANTOPENOBJ (H5OPEN H5E_CANTOPENOBJ_g) +#define H5E_CANTCLOSEOBJ (H5OPEN H5E_CANTCLOSEOBJ_g) +#define H5E_COMPLEN (H5OPEN H5E_COMPLEN_g) +#define H5E_PATH (H5OPEN H5E_PATH_g) +H5_DLLVAR hid_t H5E_CANTOPENOBJ_g; /* Can't open object */ +H5_DLLVAR hid_t H5E_CANTCLOSEOBJ_g; /* Can't close object */ +H5_DLLVAR hid_t H5E_COMPLEN_g; /* Name component is too long */ +H5_DLLVAR hid_t H5E_PATH_g; /* Problem with path to object */ + +/* Plugin errors */ +#define H5E_OPENERROR (H5OPEN H5E_OPENERROR_g) +H5_DLLVAR hid_t H5E_OPENERROR_g; /* Can't open directory or file */ + +/* File accessibility errors */ +#define H5E_FILEEXISTS (H5OPEN H5E_FILEEXISTS_g) +#define H5E_FILEOPEN (H5OPEN H5E_FILEOPEN_g) +#define H5E_CANTCREATE (H5OPEN H5E_CANTCREATE_g) +#define H5E_CANTOPENFILE (H5OPEN H5E_CANTOPENFILE_g) +#define H5E_CANTCLOSEFILE (H5OPEN H5E_CANTCLOSEFILE_g) +#define H5E_NOTHDF5 (H5OPEN H5E_NOTHDF5_g) +#define H5E_BADFILE (H5OPEN H5E_BADFILE_g) +#define H5E_TRUNCATED (H5OPEN H5E_TRUNCATED_g) +#define H5E_MOUNT (H5OPEN H5E_MOUNT_g) +H5_DLLVAR hid_t H5E_FILEEXISTS_g; /* File already exists */ +H5_DLLVAR hid_t H5E_FILEOPEN_g; /* File already open */ +H5_DLLVAR hid_t H5E_CANTCREATE_g; /* Unable to create file */ +H5_DLLVAR hid_t H5E_CANTOPENFILE_g; /* Unable to open file */ +H5_DLLVAR hid_t H5E_CANTCLOSEFILE_g; /* Unable to close file */ +H5_DLLVAR hid_t H5E_NOTHDF5_g; /* Not an HDF5 file */ +H5_DLLVAR hid_t H5E_BADFILE_g; /* Bad file ID accessed */ +H5_DLLVAR hid_t H5E_TRUNCATED_g; /* File has been truncated */ +H5_DLLVAR hid_t H5E_MOUNT_g; /* File mount error */ + +/* Dataspace errors */ +#define H5E_CANTCLIP (H5OPEN H5E_CANTCLIP_g) +#define H5E_CANTCOUNT (H5OPEN H5E_CANTCOUNT_g) +#define H5E_CANTSELECT (H5OPEN H5E_CANTSELECT_g) +#define H5E_CANTNEXT (H5OPEN H5E_CANTNEXT_g) +#define H5E_BADSELECT (H5OPEN H5E_BADSELECT_g) +#define H5E_CANTCOMPARE (H5OPEN H5E_CANTCOMPARE_g) +H5_DLLVAR hid_t H5E_CANTCLIP_g; /* Can't clip hyperslab region */ +H5_DLLVAR hid_t H5E_CANTCOUNT_g; /* Can't count elements */ +H5_DLLVAR hid_t H5E_CANTSELECT_g; /* Can't select hyperslab */ +H5_DLLVAR hid_t H5E_CANTNEXT_g; /* Can't move to next iterator location */ +H5_DLLVAR hid_t H5E_BADSELECT_g; /* Invalid selection */ +H5_DLLVAR hid_t H5E_CANTCOMPARE_g; /* Can't compare objects */ /* Cache related errors */ #define H5E_CANTFLUSH (H5OPEN H5E_CANTFLUSH_g) @@ -139,45 +233,51 @@ H5_DLLVAR hid_t H5E_CANTDIRTY_g; /* Unable to mark metadata as dirty */ H5_DLLVAR hid_t H5E_CANTEXPUNGE_g; /* Unable to expunge a metadata cache entry */ H5_DLLVAR hid_t H5E_CANTRESIZE_g; /* Unable to resize a metadata cache entry */ +/* Free space errors */ +#define H5E_CANTMERGE (H5OPEN H5E_CANTMERGE_g) +#define H5E_CANTREVIVE (H5OPEN H5E_CANTREVIVE_g) +#define H5E_CANTSHRINK (H5OPEN H5E_CANTSHRINK_g) +H5_DLLVAR hid_t H5E_CANTMERGE_g; /* Can't merge objects */ +H5_DLLVAR hid_t H5E_CANTREVIVE_g; /* Can't revive object */ +H5_DLLVAR hid_t H5E_CANTSHRINK_g; /* Can't shrink container */ + /* Datatype conversion errors */ #define H5E_CANTCONVERT (H5OPEN H5E_CANTCONVERT_g) #define H5E_BADSIZE (H5OPEN H5E_BADSIZE_g) H5_DLLVAR hid_t H5E_CANTCONVERT_g; /* Can't convert datatypes */ H5_DLLVAR hid_t H5E_BADSIZE_g; /* Bad size for object */ -/* Argument errors */ -#define H5E_UNINITIALIZED (H5OPEN H5E_UNINITIALIZED_g) -#define H5E_UNSUPPORTED (H5OPEN H5E_UNSUPPORTED_g) -#define H5E_BADTYPE (H5OPEN H5E_BADTYPE_g) -#define H5E_BADRANGE (H5OPEN H5E_BADRANGE_g) -#define H5E_BADVALUE (H5OPEN H5E_BADVALUE_g) -H5_DLLVAR hid_t H5E_UNINITIALIZED_g; /* Information is uinitialized */ -H5_DLLVAR hid_t H5E_UNSUPPORTED_g; /* Feature is unsupported */ -H5_DLLVAR hid_t H5E_BADTYPE_g; /* Inappropriate type */ -H5_DLLVAR hid_t H5E_BADRANGE_g; /* Out of range */ -H5_DLLVAR hid_t H5E_BADVALUE_g; /* Bad value */ +/* Parallel MPI errors */ +#define H5E_MPI (H5OPEN H5E_MPI_g) +#define H5E_MPIERRSTR (H5OPEN H5E_MPIERRSTR_g) +#define H5E_CANTRECV (H5OPEN H5E_CANTRECV_g) +H5_DLLVAR hid_t H5E_MPI_g; /* Some MPI function failed */ +H5_DLLVAR hid_t H5E_MPIERRSTR_g; /* MPI Error String */ +H5_DLLVAR hid_t H5E_CANTRECV_g; /* Can't receive data */ -/* Resource errors */ -#define H5E_NOSPACE (H5OPEN H5E_NOSPACE_g) -#define H5E_CANTALLOC (H5OPEN H5E_CANTALLOC_g) -#define H5E_CANTCOPY (H5OPEN H5E_CANTCOPY_g) -#define H5E_CANTFREE (H5OPEN H5E_CANTFREE_g) -#define H5E_ALREADYEXISTS (H5OPEN H5E_ALREADYEXISTS_g) -#define H5E_CANTLOCK (H5OPEN H5E_CANTLOCK_g) -#define H5E_CANTUNLOCK (H5OPEN H5E_CANTUNLOCK_g) -#define H5E_CANTGC (H5OPEN H5E_CANTGC_g) -#define H5E_CANTGETSIZE (H5OPEN H5E_CANTGETSIZE_g) -#define H5E_OBJOPEN (H5OPEN H5E_OBJOPEN_g) -H5_DLLVAR hid_t H5E_NOSPACE_g; /* No space available for allocation */ -H5_DLLVAR hid_t H5E_CANTALLOC_g; /* Can't allocate space */ -H5_DLLVAR hid_t H5E_CANTCOPY_g; /* Unable to copy object */ -H5_DLLVAR hid_t H5E_CANTFREE_g; /* Unable to free object */ -H5_DLLVAR hid_t H5E_ALREADYEXISTS_g; /* Object already exists */ -H5_DLLVAR hid_t H5E_CANTLOCK_g; /* Unable to lock object */ -H5_DLLVAR hid_t H5E_CANTUNLOCK_g; /* Unable to unlock object */ -H5_DLLVAR hid_t H5E_CANTGC_g; /* Unable to garbage collect */ -H5_DLLVAR hid_t H5E_CANTGETSIZE_g; /* Unable to compute size */ -H5_DLLVAR hid_t H5E_OBJOPEN_g; /* Object is already open */ +/* Property list errors */ +#define H5E_CANTGET (H5OPEN H5E_CANTGET_g) +#define H5E_CANTSET (H5OPEN H5E_CANTSET_g) +#define H5E_DUPCLASS (H5OPEN H5E_DUPCLASS_g) +#define H5E_SETDISALLOWED (H5OPEN H5E_SETDISALLOWED_g) +H5_DLLVAR hid_t H5E_CANTGET_g; /* Can't get value */ +H5_DLLVAR hid_t H5E_CANTSET_g; /* Can't set value */ +H5_DLLVAR hid_t H5E_DUPCLASS_g; /* Duplicate class name in parent class */ +H5_DLLVAR hid_t H5E_SETDISALLOWED_g; /* Disallowed operation */ + +/* Generic low-level file I/O errors */ +#define H5E_SEEKERROR (H5OPEN H5E_SEEKERROR_g) +#define H5E_READERROR (H5OPEN H5E_READERROR_g) +#define H5E_WRITEERROR (H5OPEN H5E_WRITEERROR_g) +#define H5E_CLOSEERROR (H5OPEN H5E_CLOSEERROR_g) +#define H5E_OVERFLOW (H5OPEN H5E_OVERFLOW_g) +#define H5E_FCNTL (H5OPEN H5E_FCNTL_g) +H5_DLLVAR hid_t H5E_SEEKERROR_g; /* Seek failed */ +H5_DLLVAR hid_t H5E_READERROR_g; /* Read failed */ +H5_DLLVAR hid_t H5E_WRITEERROR_g; /* Write failed */ +H5_DLLVAR hid_t H5E_CLOSEERROR_g; /* Close failed */ +H5_DLLVAR hid_t H5E_OVERFLOW_g; /* Address overflowed */ +H5_DLLVAR hid_t H5E_FCNTL_g; /* File control (fcntl) failed */ /* Object header related errors */ #define H5E_LINKCOUNT (H5OPEN H5E_LINKCOUNT_g) @@ -199,66 +299,6 @@ H5_DLLVAR hid_t H5E_CANTPACK_g; /* Can't pack messages */ H5_DLLVAR hid_t H5E_CANTRESET_g; /* Can't reset object */ H5_DLLVAR hid_t H5E_CANTRENAME_g; /* Unable to rename object */ -/* Generic low-level file I/O errors */ -#define H5E_SEEKERROR (H5OPEN H5E_SEEKERROR_g) -#define H5E_READERROR (H5OPEN H5E_READERROR_g) -#define H5E_WRITEERROR (H5OPEN H5E_WRITEERROR_g) -#define H5E_CLOSEERROR (H5OPEN H5E_CLOSEERROR_g) -#define H5E_OVERFLOW (H5OPEN H5E_OVERFLOW_g) -#define H5E_FCNTL (H5OPEN H5E_FCNTL_g) -H5_DLLVAR hid_t H5E_SEEKERROR_g; /* Seek failed */ -H5_DLLVAR hid_t H5E_READERROR_g; /* Read failed */ -H5_DLLVAR hid_t H5E_WRITEERROR_g; /* Write failed */ -H5_DLLVAR hid_t H5E_CLOSEERROR_g; /* Close failed */ -H5_DLLVAR hid_t H5E_OVERFLOW_g; /* Address overflowed */ -H5_DLLVAR hid_t H5E_FCNTL_g; /* File control (fcntl) failed */ - -/* File accessibility errors */ -#define H5E_FILEEXISTS (H5OPEN H5E_FILEEXISTS_g) -#define H5E_FILEOPEN (H5OPEN H5E_FILEOPEN_g) -#define H5E_CANTCREATE (H5OPEN H5E_CANTCREATE_g) -#define H5E_CANTOPENFILE (H5OPEN H5E_CANTOPENFILE_g) -#define H5E_CANTCLOSEFILE (H5OPEN H5E_CANTCLOSEFILE_g) -#define H5E_NOTHDF5 (H5OPEN H5E_NOTHDF5_g) -#define H5E_BADFILE (H5OPEN H5E_BADFILE_g) -#define H5E_TRUNCATED (H5OPEN H5E_TRUNCATED_g) -#define H5E_MOUNT (H5OPEN H5E_MOUNT_g) -H5_DLLVAR hid_t H5E_FILEEXISTS_g; /* File already exists */ -H5_DLLVAR hid_t H5E_FILEOPEN_g; /* File already open */ -H5_DLLVAR hid_t H5E_CANTCREATE_g; /* Unable to create file */ -H5_DLLVAR hid_t H5E_CANTOPENFILE_g; /* Unable to open file */ -H5_DLLVAR hid_t H5E_CANTCLOSEFILE_g; /* Unable to close file */ -H5_DLLVAR hid_t H5E_NOTHDF5_g; /* Not an HDF5 file */ -H5_DLLVAR hid_t H5E_BADFILE_g; /* Bad file ID accessed */ -H5_DLLVAR hid_t H5E_TRUNCATED_g; /* File has been truncated */ -H5_DLLVAR hid_t H5E_MOUNT_g; /* File mount error */ - -/* No error */ -#define H5E_NONE_MINOR (H5OPEN H5E_NONE_MINOR_g) -H5_DLLVAR hid_t H5E_NONE_MINOR_g; /* No error */ - -/* Heap errors */ -#define H5E_CANTRESTORE (H5OPEN H5E_CANTRESTORE_g) -#define H5E_CANTCOMPUTE (H5OPEN H5E_CANTCOMPUTE_g) -#define H5E_CANTEXTEND (H5OPEN H5E_CANTEXTEND_g) -#define H5E_CANTATTACH (H5OPEN H5E_CANTATTACH_g) -#define H5E_CANTUPDATE (H5OPEN H5E_CANTUPDATE_g) -#define H5E_CANTOPERATE (H5OPEN H5E_CANTOPERATE_g) -H5_DLLVAR hid_t H5E_CANTRESTORE_g; /* Can't restore condition */ -H5_DLLVAR hid_t H5E_CANTCOMPUTE_g; /* Can't compute value */ -H5_DLLVAR hid_t H5E_CANTEXTEND_g; /* Can't extend heap's space */ -H5_DLLVAR hid_t H5E_CANTATTACH_g; /* Can't attach object */ -H5_DLLVAR hid_t H5E_CANTUPDATE_g; /* Can't update object */ -H5_DLLVAR hid_t H5E_CANTOPERATE_g; /* Can't operate on object */ - -/* Function entry/exit interface errors */ -#define H5E_CANTINIT (H5OPEN H5E_CANTINIT_g) -#define H5E_ALREADYINIT (H5OPEN H5E_ALREADYINIT_g) -#define H5E_CANTRELEASE (H5OPEN H5E_CANTRELEASE_g) -H5_DLLVAR hid_t H5E_CANTINIT_g; /* Unable to initialize object */ -H5_DLLVAR hid_t H5E_ALREADYINIT_g; /* Object already initialized */ -H5_DLLVAR hid_t H5E_CANTRELEASE_g; /* Unable to release object */ - /* B-tree related errors */ #define H5E_NOTFOUND (H5OPEN H5E_NOTFOUND_g) #define H5E_EXISTS (H5OPEN H5E_EXISTS_g) @@ -283,89 +323,49 @@ H5_DLLVAR hid_t H5E_CANTLIST_g; /* Unable to list node */ H5_DLLVAR hid_t H5E_CANTMODIFY_g; /* Unable to modify record */ H5_DLLVAR hid_t H5E_CANTREMOVE_g; /* Unable to remove object */ -/* Group related errors */ -#define H5E_CANTOPENOBJ (H5OPEN H5E_CANTOPENOBJ_g) -#define H5E_CANTCLOSEOBJ (H5OPEN H5E_CANTCLOSEOBJ_g) -#define H5E_COMPLEN (H5OPEN H5E_COMPLEN_g) -#define H5E_PATH (H5OPEN H5E_PATH_g) -H5_DLLVAR hid_t H5E_CANTOPENOBJ_g; /* Can't open object */ -H5_DLLVAR hid_t H5E_CANTCLOSEOBJ_g; /* Can't close object */ -H5_DLLVAR hid_t H5E_COMPLEN_g; /* Name component is too long */ -H5_DLLVAR hid_t H5E_PATH_g; /* Problem with path to object */ - -/* Parallel MPI errors */ -#define H5E_MPI (H5OPEN H5E_MPI_g) -#define H5E_MPIERRSTR (H5OPEN H5E_MPIERRSTR_g) -#define H5E_CANTRECV (H5OPEN H5E_CANTRECV_g) -H5_DLLVAR hid_t H5E_MPI_g; /* Some MPI function failed */ -H5_DLLVAR hid_t H5E_MPIERRSTR_g; /* MPI Error String */ -H5_DLLVAR hid_t H5E_CANTRECV_g; /* Can't receive data */ - -/* System level errors */ -#define H5E_SYSERRSTR (H5OPEN H5E_SYSERRSTR_g) -H5_DLLVAR hid_t H5E_SYSERRSTR_g; /* System error message */ - -/* Link related errors */ -#define H5E_TRAVERSE (H5OPEN H5E_TRAVERSE_g) -#define H5E_NLINKS (H5OPEN H5E_NLINKS_g) -#define H5E_NOTREGISTERED (H5OPEN H5E_NOTREGISTERED_g) -#define H5E_CANTMOVE (H5OPEN H5E_CANTMOVE_g) -#define H5E_CANTSORT (H5OPEN H5E_CANTSORT_g) -H5_DLLVAR hid_t H5E_TRAVERSE_g; /* Link traversal failure */ -H5_DLLVAR hid_t H5E_NLINKS_g; /* Too many soft links in path */ -H5_DLLVAR hid_t H5E_NOTREGISTERED_g; /* Link class not registered */ -H5_DLLVAR hid_t H5E_CANTMOVE_g; /* Can't move object */ -H5_DLLVAR hid_t H5E_CANTSORT_g; /* Can't sort objects */ - -/* I/O pipeline errors */ -#define H5E_NOFILTER (H5OPEN H5E_NOFILTER_g) -#define H5E_CALLBACK (H5OPEN H5E_CALLBACK_g) -#define H5E_CANAPPLY (H5OPEN H5E_CANAPPLY_g) -#define H5E_SETLOCAL (H5OPEN H5E_SETLOCAL_g) -#define H5E_NOENCODER (H5OPEN H5E_NOENCODER_g) -#define H5E_CANTFILTER (H5OPEN H5E_CANTFILTER_g) -H5_DLLVAR hid_t H5E_NOFILTER_g; /* Requested filter is not available */ -H5_DLLVAR hid_t H5E_CALLBACK_g; /* Callback failed */ -H5_DLLVAR hid_t H5E_CANAPPLY_g; /* Error from filter 'can apply' callback */ -H5_DLLVAR hid_t H5E_SETLOCAL_g; /* Error from filter 'set local' callback */ -H5_DLLVAR hid_t H5E_NOENCODER_g; /* Filter present but encoding disabled */ -H5_DLLVAR hid_t H5E_CANTFILTER_g; /* Filter operation failed */ - -/* Property list errors */ -#define H5E_CANTGET (H5OPEN H5E_CANTGET_g) -#define H5E_CANTSET (H5OPEN H5E_CANTSET_g) -#define H5E_DUPCLASS (H5OPEN H5E_DUPCLASS_g) -#define H5E_SETDISALLOWED (H5OPEN H5E_SETDISALLOWED_g) -H5_DLLVAR hid_t H5E_CANTGET_g; /* Can't get value */ -H5_DLLVAR hid_t H5E_CANTSET_g; /* Can't set value */ -H5_DLLVAR hid_t H5E_DUPCLASS_g; /* Duplicate class name in parent class */ -H5_DLLVAR hid_t H5E_SETDISALLOWED_g; /* Disallowed operation */ - -/* Free space errors */ -#define H5E_CANTMERGE (H5OPEN H5E_CANTMERGE_g) -#define H5E_CANTREVIVE (H5OPEN H5E_CANTREVIVE_g) -#define H5E_CANTSHRINK (H5OPEN H5E_CANTSHRINK_g) -H5_DLLVAR hid_t H5E_CANTMERGE_g; /* Can't merge objects */ -H5_DLLVAR hid_t H5E_CANTREVIVE_g; /* Can't revive object */ -H5_DLLVAR hid_t H5E_CANTSHRINK_g; /* Can't shrink container */ +/* Resource errors */ +#define H5E_NOSPACE (H5OPEN H5E_NOSPACE_g) +#define H5E_CANTALLOC (H5OPEN H5E_CANTALLOC_g) +#define H5E_CANTCOPY (H5OPEN H5E_CANTCOPY_g) +#define H5E_CANTFREE (H5OPEN H5E_CANTFREE_g) +#define H5E_ALREADYEXISTS (H5OPEN H5E_ALREADYEXISTS_g) +#define H5E_CANTLOCK (H5OPEN H5E_CANTLOCK_g) +#define H5E_CANTUNLOCK (H5OPEN H5E_CANTUNLOCK_g) +#define H5E_CANTGC (H5OPEN H5E_CANTGC_g) +#define H5E_CANTGETSIZE (H5OPEN H5E_CANTGETSIZE_g) +#define H5E_OBJOPEN (H5OPEN H5E_OBJOPEN_g) +H5_DLLVAR hid_t H5E_NOSPACE_g; /* No space available for allocation */ +H5_DLLVAR hid_t H5E_CANTALLOC_g; /* Can't allocate space */ +H5_DLLVAR hid_t H5E_CANTCOPY_g; /* Unable to copy object */ +H5_DLLVAR hid_t H5E_CANTFREE_g; /* Unable to free object */ +H5_DLLVAR hid_t H5E_ALREADYEXISTS_g; /* Object already exists */ +H5_DLLVAR hid_t H5E_CANTLOCK_g; /* Unable to lock object */ +H5_DLLVAR hid_t H5E_CANTUNLOCK_g; /* Unable to unlock object */ +H5_DLLVAR hid_t H5E_CANTGC_g; /* Unable to garbage collect */ +H5_DLLVAR hid_t H5E_CANTGETSIZE_g; /* Unable to compute size */ +H5_DLLVAR hid_t H5E_OBJOPEN_g; /* Object is already open */ -/* Dataspace errors */ -#define H5E_CANTCLIP (H5OPEN H5E_CANTCLIP_g) -#define H5E_CANTCOUNT (H5OPEN H5E_CANTCOUNT_g) -#define H5E_CANTSELECT (H5OPEN H5E_CANTSELECT_g) -#define H5E_CANTNEXT (H5OPEN H5E_CANTNEXT_g) -#define H5E_BADSELECT (H5OPEN H5E_BADSELECT_g) -#define H5E_CANTCOMPARE (H5OPEN H5E_CANTCOMPARE_g) -H5_DLLVAR hid_t H5E_CANTCLIP_g; /* Can't clip hyperslab region */ -H5_DLLVAR hid_t H5E_CANTCOUNT_g; /* Can't count elements */ -H5_DLLVAR hid_t H5E_CANTSELECT_g; /* Can't select hyperslab */ -H5_DLLVAR hid_t H5E_CANTNEXT_g; /* Can't move to next iterator location */ -H5_DLLVAR hid_t H5E_BADSELECT_g; /* Invalid selection */ -H5_DLLVAR hid_t H5E_CANTCOMPARE_g; /* Can't compare objects */ +/* Object atom related errors */ +#define H5E_BADATOM (H5OPEN H5E_BADATOM_g) +#define H5E_BADGROUP (H5OPEN H5E_BADGROUP_g) +#define H5E_CANTREGISTER (H5OPEN H5E_CANTREGISTER_g) +#define H5E_CANTINC (H5OPEN H5E_CANTINC_g) +#define H5E_CANTDEC (H5OPEN H5E_CANTDEC_g) +#define H5E_NOIDS (H5OPEN H5E_NOIDS_g) +H5_DLLVAR hid_t H5E_BADATOM_g; /* Unable to find atom information (already closed?) */ +H5_DLLVAR hid_t H5E_BADGROUP_g; /* Unable to find ID group information */ +H5_DLLVAR hid_t H5E_CANTREGISTER_g; /* Unable to register new atom */ +H5_DLLVAR hid_t H5E_CANTINC_g; /* Unable to increment reference count */ +H5_DLLVAR hid_t H5E_CANTDEC_g; /* Unable to decrement reference count */ +H5_DLLVAR hid_t H5E_NOIDS_g; /* Out of IDs for group */ -/* Plugin errors */ -#define H5E_OPENERROR (H5OPEN H5E_OPENERROR_g) -H5_DLLVAR hid_t H5E_OPENERROR_g; /* Can't open directory or file */ +/* Function entry/exit interface errors */ +#define H5E_CANTINIT (H5OPEN H5E_CANTINIT_g) +#define H5E_ALREADYINIT (H5OPEN H5E_ALREADYINIT_g) +#define H5E_CANTRELEASE (H5OPEN H5E_CANTRELEASE_g) +H5_DLLVAR hid_t H5E_CANTINIT_g; /* Unable to initialize object */ +H5_DLLVAR hid_t H5E_ALREADYINIT_g; /* Object already initialized */ +H5_DLLVAR hid_t H5E_CANTRELEASE_g; /* Unable to release object */ #ifdef __cplusplus } diff --git a/src/H5Epublic.h b/src/H5Epublic.h index 72c3884..3fd6cce 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -26,18 +26,29 @@ /* Value for the default error stack */ #define H5E_DEFAULT (hid_t)0 -/* Different kinds of error information */ +/** + * Different kinds of error information + */ typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t; -/* Information about an error; element of error stack */ +/** + * Information about an error; element of error stack + */ typedef struct H5E_error2_t { - hid_t cls_id; /*class ID */ - hid_t maj_num; /*major error ID */ - hid_t min_num; /*minor error number */ - unsigned line; /*line in file where error occurs */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - const char *desc; /*optional supplied description */ + hid_t cls_id; + /**< Class ID */ + hid_t maj_num; + /**< Major error ID */ + hid_t min_num; + /**< Minor error number */ + unsigned line; + /**< Line in file where error occurs */ + const char *func_name; + /**< Function in which error occurred */ + const char *file_name; + /**< File in which error occurred */ + const char *desc; + /**< Optional supplied description */ } H5E_error2_t; /* When this header is included from a private header, don't make calls to H5open() */ @@ -138,10 +149,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; goto label; \ } -/* Error stack traversal direction */ +/** + * Error stack traversal direction + */ typedef enum H5E_direction_t { - H5E_WALK_UPWARD = 0, /*begin deep, end at API function */ - H5E_WALK_DOWNWARD = 1 /*begin at API function, end deep */ + H5E_WALK_UPWARD = 0, /**< begin w/ most specific error, end at API function */ + H5E_WALK_DOWNWARD = 1 /**< begin at API function, end w/ most specific error */ } H5E_direction_t; #ifdef __cplusplus @@ -149,29 +162,478 @@ extern "C" { #endif /* Error stack traversal callback function pointers */ +//! <!-- [H5E_walk2_t_snip] --> +/** + * \brief Callback function for H5Ewalk2() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data); +//! <!-- [H5E_walk2_t_snip] --> + +//! <!-- [H5E_auto2_t_snip] --> +/** + * \brief Callback function for H5Eset_auto2() + * + * \estack_id{estack} + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); +//! <!-- [H5E_auto2_t_snip] --> /* Public API functions */ -H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); -H5_DLL herr_t H5Eunregister_class(hid_t class_id); -H5_DLL herr_t H5Eclose_msg(hid_t err_id); -H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); -H5_DLL hid_t H5Ecreate_stack(void); -H5_DLL hid_t H5Eget_current_stack(void); -H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Registers a client library or application program to the HDF5 error API + * + * \param[in] cls_name Name of the error class + * \param[in] lib_name Name of the client library or application to which the error class belongs + * \param[in] version Version of the client library or application to which the + error class belongs. Can be \c NULL. + * \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID. + * + * \details H5Eregister_class() registers a client library or application + * program to the HDF5 error API so that the client library or + * application program can report errors together with the HDF5 + * library. It receives an identifier for this error class for further + * error operations. The library name and version number will be + * printed out in the error message as a preamble. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Removes an error class + * + * \param[in] class_id Error class identifier. + * \return \herr_t + * + * \details H5Eunregister_class() removes the error class specified by \p + * class_id. All the major and minor errors in this class will also be + * closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eunregister_class(hid_t class_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error message + * + * \param[in] err_id An error message identifier + * \return \herr_t + * + * \details H5Eclose_msg() closes an error message identifier, which can be + * either a major or minor message. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_msg(hid_t err_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Adds a major error message to an error class + * + * \param[in] cls An error class identifier + * \param[in] msg_type The type of the error message + * \param[in] msg Major error message + * \return \herr_t + * + * \details H5Ecreate_msg() adds an error message to an error class defined by + * client library or application program. The error message can be + * either major or minor as indicated by the parameter \p msg_type. + * + * Use H5Eclose_msg() to close the message identifier returned by this + * function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Creates a new, empty error stack + * + * \return \hid_ti{error stack} + * + * \details H5Ecreate_stack() creates a new empty error stack and returns the + * new stack’s identifier. Use H5Eclose_stack() to close the error stack + * identifier returned by this function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a copy of the current error stack + * + * \return \hid_ti{error stack} + * + * \details H5Eget_current_stack() copies the current error stack and returns an + * error stack identifier for the new copy. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eget_current_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error stack handle + * + * \estack_id{stack_id} + * + * \return \herr_t + * + * \details H5Eclose_stack() closes the error stack handle \p stack_id + * and releases its resources. #H5E_DEFAULT cannot be closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves error class name + * + * \param[in] class_id Error class identifier + * \param[out] name Buffer for the error class name + * \param[in] size The maximum number of characters the class name to be returned + * by this function in\p name. + * \return Returns non-negative value as on success; otherwise returns negative value. + * + * \details H5Eget_class_name() retrieves the name of the error class specified + * by the class identifier. If non-NULL pointer is passed in for \p + * name and \p size is greater than zero, the class name of \p size + * long is returned. The length of the error class name is also + * returned. If NULL is passed in as \p name, only the length of class + * name is returned. If zero is returned, it means no name. The user is + * responsible for allocating sufficient buffer space for the name. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size); -H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); -H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, - hid_t maj_id, hid_t min_id, const char *msg, ...); -H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); -H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); -H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); -H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); -H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); -H5_DLL herr_t H5Eclear2(hid_t err_stack); -H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Replaces the current error stack + * + * \estack_id{err_stack_id} + * + * \return \herr_t + * + * \details H5Eset_current_stack() replaces the content of the current error + * stack with a copy of the content of the error stack specified by + * \p err_stack_id, and it closes the error stack specified by + * \p err_stack_id. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto an error stack + * + * \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record + * will be pushed to the current stack. + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] cls_id Error class identifier + * \param[in] maj_id Major error identifier + * \param[in] min_id Minor error identifier + * \param[in] msg Error description string + * \return \herr_t + * + * \details H5Epush2() pushes a new error record onto the error stack specified + * by \p err_stack.\n + * The error record contains the error class identifier \p cls_id, the + * major and minor message identifiers \p maj_id and \p min_id, the + * function name \p func where the error was detected, the file name \p + * file and line number \p line in the file where the error was + * detected, and an error description \p msg.\n + * The major and minor errors must be in the same error class.\n + * The function name, filename, and error description strings must be + * statically allocated.\n + * \p msg can be a format control string with additional + * arguments. This design of appending additional arguments is similar + * to the system and C functions printf() and fprintf(). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, + hid_t maj_id, hid_t min_id, const char *msg, ...); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Deletes specified number of error messages from the error stack + * + * \estack_id{err_stack} + * \param[in] count The number of error messages to be deleted from the top + * of error stack + * \return \herr_t + * + * \details H5Epop() deletes the number of error records specified in \p count + * from the top of the error stack specified by \p err_stack (including + * major, minor messages and description). The number of error messages + * to be deleted is specified by \p count. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the specified error stack in a default manner + * + * \estack_id{err_stack} + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint2() prints the error stack specified by \p err_stack on the + * specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0. + * \endcode + * + * A similar line will appear before the error messages of each error + * class stating the library name, library version number, and thread + * identifier. + * + * If \p err_stack is #H5E_DEFAULT, the current error stack will be + * printed. + * + * H5Eprint2() is a convenience function for H5Ewalk2() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the specified error stack, calling the specified function + * + * \estack_id{err_stack} + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk2() walks the error stack specified by err_stack for the + * current thread and calls the function specified in \p func for each + * error along the way. + * + * If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks + * the current error stack. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk2_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype + * is as follows: + * \snippet this H5E_walk2_t_snip + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the settings for the automatic error stack traversal + * function and its data + * + * \estack_id + * \param[out] func The function currently set to be called upon an error condition + * \param[out] client_data Data currently set to be passed to the error function + * \return \herr_t + * + * \details H5Eget_auto2() returns the settings for the automatic error stack + * traversal function, \p func, and its data, \p client_data, that are + * associated with the error stack specified by \p estack_id. + * + * Either or both of the \p func and \p client_data arguments may be + * \c NULL, in which case the value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \estack_id + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto2() turns on or off automatic printing of errors for the + * error stack specified with \p estack_id. An \p estack_id value of + * #H5E_DEFAULT indicates the current stack. + * + * When automatic printing is turned on, by the use of a non-null \p func + * pointer, any API function which returns an error indication will + * first call \p func, passing it \p client_data as an argument. + * + * \p func, a function compliant with the #H5E_auto2_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto2_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint2() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * Automatic error printing is turned off with a H5Eset_auto2() call + * with a \c NULL \p func pointer. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the specified error stack or the error stack for the current thread + * + * \estack_id{err_stack} + * \return \herr_t + * + * \details H5Eclear2() clears the error stack specified by \p err_stack, or, if + * \p err_stack is set to #H5E_DEFAULT, the error stack for the current + * thread. + * + * \p err_stack is an error stack identifier, such as that returned by + * H5Eget_current_stack(). + * + * The current error stack is also cleared whenever an API function is + * called, with certain exceptions (for instance, H5Eprint1() or + * H5Eprint2()). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclear2(hid_t err_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Determines the type of error stack + * + * \estack_id{err_stack} + * \param[out] is_stack A flag indicating which error stack \c typedef the + * specified error stack conforms to + * + * \return \herr_t + * + * \details H5Eauto_is_v2() determines whether the error auto reporting function + * for an error stack conforms to the #H5E_auto2_t \c typedef or the + * #H5E_auto1_t \c typedef. + * + * The \p is_stack parameter is set to 1 if the error stack conforms to + * #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves an error message + * + * \param[in] msg_id Error message identifier + * \param[out] type The type of the error message Valid values are #H5E_MAJOR + * and #H5E_MINOR. + * \param[out] msg Error message buffer + * \param[in] size The length of error message to be returned by this function + * \return Returns the size of the error message in bytes on success; otherwise + * returns a negative value. + * + * \details H5Eget_msg() retrieves the error message including its length and + * type. The error message is specified by \p msg_id. The user is + * responsible for passing in sufficient buffer space for the + * message. If \p msg is not NULL and \p size is greater than zero, the + * error message of \p size long is returned. The length of the message + * is also returned. If NULL is passed in as \p msg, only the length + * and type of the message is returned. If the return value is zero, it + * means there is no message. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves the number of error messages in an error stack + * + * \estack_id{error_stack_id} + * \return Returns a non-negative value on success; otherwise returns a negative value. + * + * \details H5Eget_num() retrieves the number of error records in the error + * stack specified by \p error_stack_id (including major, minor + * messages and description). + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -188,30 +650,259 @@ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); typedef hid_t H5E_major_t; typedef hid_t H5E_minor_t; -/* Information about an error element of error stack. */ +/** + * Information about an error element of error stack. + */ typedef struct H5E_error1_t { - H5E_major_t maj_num; /*major error number */ - H5E_minor_t min_num; /*minor error number */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - unsigned line; /*line in file where error occurs */ - const char *desc; /*optional supplied description */ + H5E_major_t maj_num; /**< major error number */ + H5E_minor_t min_num; /**< minor error number */ + const char *func_name; /**< function in which error occurred */ + const char *file_name; /**< file in which error occurred */ + unsigned line; /**< line in file where error occurs */ + const char *desc; /**< optional supplied description */ } H5E_error1_t; /* Error stack traversal callback function pointers */ +//! <!-- [H5E_walk1_t_snip] --> +/** + * \brief Callback function for H5Ewalk1() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data); +//! <!-- [H5E_walk1_t_snip] --> + +//! <!-- [H5E_auto1_t_snip] --> +/** + * \brief Callback function for H5Eset_auto1() + * + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto1_t)(void *client_data); +//! <!-- [H5E_auto1_t_snip] --> /* Function prototypes */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the error stack for the current thread + * + * \return \herr_t + * + * \details H5Eclear1() clears the error stack for the current thread.\n + * The stack is also cleared whenever an API function is called, with + * certain exceptions (for instance, H5Eprint1()). + * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + */ H5_DLL herr_t H5Eclear1(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the current settings for the automatic error stack traversal + * function and its data + * + * \param[out] func Current setting for the function to be called upon an error + * condition + * \param[out] client_data Current setting for the data passed to the error + * function + * \return \herr_t + * + * \details H5Eget_auto1() returns the current settings for the automatic error + * stack traversal function, \p func, and its data, + * \p client_data. Either or both arguments may be \c NULL, in which case the + * value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto the error stack + * + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] maj Major error identifier + * \param[in] min Minor error identifier + * \param[in] str Error description string + * \return \herr_t + * + * \details H5Epush1() pushes a new error record onto the error stack for the + * current thread.\n + * The error has major and minor numbers \p maj_num + * and \p min_num, the function \p func where the error was detected, the + * name of the file \p file where the error was detected, the line \p line + * within that file, and an error description string \p str.\n + * The function name, filename, and error description strings must be statically + * allocated. + * + * \since 1.4.0 + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the current error stack in a default manner + * + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint1() prints prints the error stack for the current thread + * on the specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in thread 0. + * \endcode + * H5Eprint1() is a convenience function for H5Ewalk1() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eprint1(FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto1() turns on or off automatic printing of errors. When + * turned on (non-null \p func pointer), any API function which returns + * an error indication will first call \p func, passing it \p + * client_data as an argument. + * + * \p func, a function conforming to the #H5E_auto1_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto1_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint1() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the current error stack, calling the specified function + * + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk1() walks the error stack for the current thread and calls + * the function specified in \p func for each error along the way. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk1_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype + * is as follows: + * \snippet this H5E_walk1_t_snip + * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); -H5_DLL char * H5Eget_major(H5E_major_t maj); -H5_DLL char * H5Eget_minor(H5E_minor_t min); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a major + * error number + * + * \param[in] maj Major error number + * \return \herr_t + * + * \details Given a major error number, H5Eget_major() returns a constant + * character string that describes the error. + * + * \attention This function returns a dynamically allocated string (\c char + * array). An application calling this function must free the memory + * associated with the return value to prevent a memory leak. + * + * \deprecated 1.8.0 Function deprecated in this release. + */ +H5_DLL char *H5Eget_major(H5E_major_t maj); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a minor + * error number + * + * \param[in] min Minor error number + * \return \herr_t + * + * \details Given a minor error number, H5Eget_minor() returns a constant + * character string that describes the error. + * + * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of + * dynamic allocated \c char array. An application calling this + * function from an HDF5 library of Release 1.8.0 or later must free + * the memory associated with the return value to prevent a memory + * leak. This is a change from the 1.6.x release series. + * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + */ +H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ #ifdef __cplusplus diff --git a/src/H5Eterm.h b/src/H5Eterm.h index 3d672a8..4c58622 100644 --- a/src/H5Eterm.h +++ b/src/H5Eterm.h @@ -20,48 +20,104 @@ /* Reset major error IDs */ -H5E_LINK_g= -H5E_FILE_g= -H5E_INTERNAL_g= -H5E_ARGS_g= -H5E_DATASPACE_g= H5E_SYM_g= -H5E_RESOURCE_g= -H5E_SLIST_g= -H5E_DATASET_g= -H5E_STORAGE_g= -H5E_EFL_g= -H5E_PLINE_g= +H5E_FILE_g= H5E_DATATYPE_g= +H5E_LINK_g= +H5E_DATASET_g= H5E_ATOM_g= +H5E_RESOURCE_g= +H5E_INTERNAL_g= H5E_CACHE_g= -H5E_ERROR_g= -H5E_OHDR_g= -H5E_IO_g= H5E_SOHM_g= +H5E_FUNC_g= H5E_RS_g= -H5E_PLUGIN_g= -H5E_TST_g= -H5E_FSPACE_g= +H5E_PLIST_g= H5E_BTREE_g= +H5E_NONE_MAJOR_g= +H5E_SLIST_g= +H5E_DATASPACE_g= +H5E_ARGS_g= H5E_REFERENCE_g= -H5E_FUNC_g= -H5E_VFL_g= -H5E_PLIST_g= +H5E_FSPACE_g= +H5E_EFL_g= +H5E_PLINE_g= +H5E_ERROR_g= +H5E_ATTR_g= H5E_HEAP_g= -H5E_NONE_MAJOR_g= -H5E_ATTR_g= (-1); +H5E_VFL_g= +H5E_OHDR_g= +H5E_IO_g= +H5E_TST_g= +H5E_STORAGE_g= +H5E_PLUGIN_g= (-1); /* Reset minor error IDs */ -/* Object atom related errors */ -H5E_BADATOM_g= -H5E_BADGROUP_g= -H5E_CANTREGISTER_g= -H5E_CANTINC_g= -H5E_CANTDEC_g= -H5E_NOIDS_g= +/* Heap errors */ +H5E_CANTRESTORE_g= +H5E_CANTCOMPUTE_g= +H5E_CANTEXTEND_g= +H5E_CANTATTACH_g= +H5E_CANTUPDATE_g= +H5E_CANTOPERATE_g= + +/* No error */ +H5E_NONE_MINOR_g= + +/* Link related errors */ +H5E_TRAVERSE_g= +H5E_NLINKS_g= +H5E_NOTREGISTERED_g= +H5E_CANTMOVE_g= +H5E_CANTSORT_g= + +/* I/O pipeline errors */ +H5E_NOFILTER_g= +H5E_CALLBACK_g= +H5E_CANAPPLY_g= +H5E_SETLOCAL_g= +H5E_NOENCODER_g= +H5E_CANTFILTER_g= + +/* System level errors */ +H5E_SYSERRSTR_g= + +/* Argument errors */ +H5E_UNINITIALIZED_g= +H5E_UNSUPPORTED_g= +H5E_BADTYPE_g= +H5E_BADRANGE_g= +H5E_BADVALUE_g= + +/* Group related errors */ +H5E_CANTOPENOBJ_g= +H5E_CANTCLOSEOBJ_g= +H5E_COMPLEN_g= +H5E_PATH_g= + +/* Plugin errors */ +H5E_OPENERROR_g= + +/* File accessibility errors */ +H5E_FILEEXISTS_g= +H5E_FILEOPEN_g= +H5E_CANTCREATE_g= +H5E_CANTOPENFILE_g= +H5E_CANTCLOSEFILE_g= +H5E_NOTHDF5_g= +H5E_BADFILE_g= +H5E_TRUNCATED_g= +H5E_MOUNT_g= + +/* Dataspace errors */ +H5E_CANTCLIP_g= +H5E_CANTCOUNT_g= +H5E_CANTSELECT_g= +H5E_CANTNEXT_g= +H5E_BADSELECT_g= +H5E_CANTCOMPARE_g= /* Cache related errors */ H5E_CANTFLUSH_g= @@ -80,28 +136,33 @@ H5E_CANTDIRTY_g= H5E_CANTEXPUNGE_g= H5E_CANTRESIZE_g= +/* Free space errors */ +H5E_CANTMERGE_g= +H5E_CANTREVIVE_g= +H5E_CANTSHRINK_g= + /* Datatype conversion errors */ H5E_CANTCONVERT_g= H5E_BADSIZE_g= -/* Argument errors */ -H5E_UNINITIALIZED_g= -H5E_UNSUPPORTED_g= -H5E_BADTYPE_g= -H5E_BADRANGE_g= -H5E_BADVALUE_g= +/* Parallel MPI errors */ +H5E_MPI_g= +H5E_MPIERRSTR_g= +H5E_CANTRECV_g= -/* Resource errors */ -H5E_NOSPACE_g= -H5E_CANTALLOC_g= -H5E_CANTCOPY_g= -H5E_CANTFREE_g= -H5E_ALREADYEXISTS_g= -H5E_CANTLOCK_g= -H5E_CANTUNLOCK_g= -H5E_CANTGC_g= -H5E_CANTGETSIZE_g= -H5E_OBJOPEN_g= +/* Property list errors */ +H5E_CANTGET_g= +H5E_CANTSET_g= +H5E_DUPCLASS_g= +H5E_SETDISALLOWED_g= + +/* Generic low-level file I/O errors */ +H5E_SEEKERROR_g= +H5E_READERROR_g= +H5E_WRITEERROR_g= +H5E_CLOSEERROR_g= +H5E_OVERFLOW_g= +H5E_FCNTL_g= /* Object header related errors */ H5E_LINKCOUNT_g= @@ -114,41 +175,6 @@ H5E_CANTPACK_g= H5E_CANTRESET_g= H5E_CANTRENAME_g= -/* Generic low-level file I/O errors */ -H5E_SEEKERROR_g= -H5E_READERROR_g= -H5E_WRITEERROR_g= -H5E_CLOSEERROR_g= -H5E_OVERFLOW_g= -H5E_FCNTL_g= - -/* File accessibility errors */ -H5E_FILEEXISTS_g= -H5E_FILEOPEN_g= -H5E_CANTCREATE_g= -H5E_CANTOPENFILE_g= -H5E_CANTCLOSEFILE_g= -H5E_NOTHDF5_g= -H5E_BADFILE_g= -H5E_TRUNCATED_g= -H5E_MOUNT_g= - -/* No error */ -H5E_NONE_MINOR_g= - -/* Heap errors */ -H5E_CANTRESTORE_g= -H5E_CANTCOMPUTE_g= -H5E_CANTEXTEND_g= -H5E_CANTATTACH_g= -H5E_CANTUPDATE_g= -H5E_CANTOPERATE_g= - -/* Function entry/exit interface errors */ -H5E_CANTINIT_g= -H5E_ALREADYINIT_g= -H5E_CANTRELEASE_g= - /* B-tree related errors */ H5E_NOTFOUND_g= H5E_EXISTS_g= @@ -162,55 +188,29 @@ H5E_CANTLIST_g= H5E_CANTMODIFY_g= H5E_CANTREMOVE_g= -/* Group related errors */ -H5E_CANTOPENOBJ_g= -H5E_CANTCLOSEOBJ_g= -H5E_COMPLEN_g= -H5E_PATH_g= - -/* Parallel MPI errors */ -H5E_MPI_g= -H5E_MPIERRSTR_g= -H5E_CANTRECV_g= - -/* System level errors */ -H5E_SYSERRSTR_g= - -/* Link related errors */ -H5E_TRAVERSE_g= -H5E_NLINKS_g= -H5E_NOTREGISTERED_g= -H5E_CANTMOVE_g= -H5E_CANTSORT_g= - -/* I/O pipeline errors */ -H5E_NOFILTER_g= -H5E_CALLBACK_g= -H5E_CANAPPLY_g= -H5E_SETLOCAL_g= -H5E_NOENCODER_g= -H5E_CANTFILTER_g= - -/* Property list errors */ -H5E_CANTGET_g= -H5E_CANTSET_g= -H5E_DUPCLASS_g= -H5E_SETDISALLOWED_g= - -/* Free space errors */ -H5E_CANTMERGE_g= -H5E_CANTREVIVE_g= -H5E_CANTSHRINK_g= +/* Resource errors */ +H5E_NOSPACE_g= +H5E_CANTALLOC_g= +H5E_CANTCOPY_g= +H5E_CANTFREE_g= +H5E_ALREADYEXISTS_g= +H5E_CANTLOCK_g= +H5E_CANTUNLOCK_g= +H5E_CANTGC_g= +H5E_CANTGETSIZE_g= +H5E_OBJOPEN_g= -/* Dataspace errors */ -H5E_CANTCLIP_g= -H5E_CANTCOUNT_g= -H5E_CANTSELECT_g= -H5E_CANTNEXT_g= -H5E_BADSELECT_g= -H5E_CANTCOMPARE_g= +/* Object atom related errors */ +H5E_BADATOM_g= +H5E_BADGROUP_g= +H5E_CANTREGISTER_g= +H5E_CANTINC_g= +H5E_CANTDEC_g= +H5E_NOIDS_g= -/* Plugin errors */ -H5E_OPENERROR_g= (-1); +/* Function entry/exit interface errors */ +H5E_CANTINIT_g= +H5E_ALREADYINIT_g= +H5E_CANTRELEASE_g= (-1); #endif /* H5Eterm_H */ diff --git a/src/H5FDcore.h b/src/H5FDcore.h index 1b59ccb..1b73978 100644 --- a/src/H5FDcore.h +++ b/src/H5FDcore.h @@ -25,9 +25,71 @@ #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_core_init(void); -H5_DLL void H5FD_core_term(void); +H5_DLL hid_t H5FD_core_init(void); +H5_DLL void H5FD_core_term(void); + +/** + * \ingroup FAPL + * + * \brief Modifies the file access property list to use the #H5FD_CORE driver + * + * \fapl_id + * \param[in] increment Size, in bytes, of memory increments + * \param[in] backing_store Boolean flag indicating whether to write the file + * contents to disk when the file is closed + * \returns \herr_t + * + * \details H5Pset_fapl_core() modifies the file access property list to use the + * #H5FD_CORE driver. + * + * The #H5FD_CORE driver enables an application to work with a file in + * memory, speeding reads and writes as no disk access is made. File + * contents are stored only in memory until the file is closed. The \p + * backing_store parameter determines whether file contents are ever + * written to disk. + * + * \p increment specifies the increment by which allocated memory is to + * be increased each time more memory is required. + * + * While using H5Fcreate() to create a core file, if the \p + * backing_store is set to 1 (TRUE), the file contents are flushed to a + * file with the same name as this core file when the file is closed or + * access to the file is terminated in memory. + * + * The application is allowed to open an existing file with #H5FD_CORE + * driver. While using H5Fopen() to open an existing file, if the \p + * backing_store is set to 1 (TRUE) and the \c flags for H5Fopen() is set to + * #H5F_ACC_RDWR, any change to the file contents are saved to the file + * when the file is closed. If \p backing_store is set to 0 (FALSE) and the \c + * flags for H5Fopen() is set to #H5F_ACC_RDWR, any change to the file + * contents will be lost when the file is closed. If the flags for + * H5Fopen() is set to #H5F_ACC_RDONLY, no change to the file is + * allowed either in memory or on file. + * + * \note Currently this driver cannot create or open family or multi files. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_core(hid_t fapl_id, size_t increment, hbool_t backing_store); + +/** + * \ingroup FAPL + * + * \brief Queries core file driver properties + * + * \fapl_id + * \param[out] increment Size, in bytes, of memory increments + * \param[out] backing_store Boolean flag indicating whether to write the file + * contents to disk when the file is closed + * \returns \herr_t + * + * \details H5Pget_fapl_core() queries the #H5FD_CORE driver properties as set + * by H5Pset_fapl_core(). + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_core(hid_t fapl_id, size_t *increment /*out*/, hbool_t *backing_store /*out*/); #ifdef __cplusplus } diff --git a/src/H5FDdirect.h b/src/H5FDdirect.h index 0a41728..44346e3 100644 --- a/src/H5FDdirect.h +++ b/src/H5FDdirect.h @@ -37,9 +37,70 @@ extern "C" { #define FBSIZE_DEF 4096 #define CBSIZE_DEF 16 * 1024 * 1024 -H5_DLL hid_t H5FD_direct_init(void); -H5_DLL void H5FD_direct_term(void); +H5_DLL hid_t H5FD_direct_init(void); +H5_DLL void H5FD_direct_term(void); + +/** + * \ingroup FAPL + * + * \brief Sets up use of the direct I/O driver + * + * \fapl_id + * \param[in] alignment Required memory alignment boundary + * \param[in] block_size File system block size + * \param[in] cbuf_size Copy buffer size + * \returns \herr_t + * + * \details H5Pset_fapl_direct() sets the file access property list, \p fapl_id, + * to use the direct I/O driver, #H5FD_DIRECT. With this driver, data + * is written to or read from the file synchronously without being + * cached by the system. + * + * File systems usually require the data address in memory, the file + * address, and the size of the data to be aligned. The HDF5 library’s + * direct I/O driver is able to handle unaligned data, though that will + * consume some additional memory resources and may slow + * performance. To get better performance, use the system function \p + * posix_memalign to align the data buffer in memory and the HDF5 + * function H5Pset_alignment() to align the data in the file. Be aware, + * however, that aligned data I/O may cause the HDF5 file to be bigger + * than the actual data size would otherwise require because the + * alignment may leave some holes in the file. + * + * \p alignment specifies the required alignment boundary in memory. + * + * \p block_size specifies the file system block size. A value of 0 + * (zero) means to use HDF5 library’s default value of 4KB. + * + * \p cbuf_size specifies the copy buffer size. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_fapl_direct(hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size); + +/** + * \ingroup FAPL + * + * \brief Retrieves direct I/O driver settings + * + * \fapl_id + * \param[out] boundary Required memory alignment boundary + * \param[out] block_size File system block size + * \param[out] cbuf_size Copy buffer size + * \returns \herr_t + * + * \details H5Pget_fapl_direct() retrieves the required memory alignment (\p + * alignment), file system block size (\p block_size), and copy buffer + * size (\p cbuf_size) settings for the direct I/O driver, #H5FD_DIRECT, + * from the file access property list \p fapl_id. + * + * See H5Pset_fapl_direct() for discussion of these values, + * requirements, and important considerations. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_fapl_direct(hid_t fapl_id, size_t *boundary /*out*/, size_t *block_size /*out*/, size_t *cbuf_size /*out*/); diff --git a/src/H5FDfamily.h b/src/H5FDfamily.h index 9d57f15..375ffce 100644 --- a/src/H5FDfamily.h +++ b/src/H5FDfamily.h @@ -26,9 +26,59 @@ extern "C" { #endif -H5_DLL hid_t H5FD_family_init(void); -H5_DLL void H5FD_family_term(void); +H5_DLL hid_t H5FD_family_init(void); +H5_DLL void H5FD_family_term(void); + +/** + * \ingroup FAPL + * + * \brief Sets the file access property list to use the family driver + * + * \fapl_id + * \param[in] memb_size Size in bytes of each file member + * \param[in] memb_fapl_id Identifier of file access property list for + * each family member + * \returns \herr_t + * + * \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 + * will be saved in file when the property list \p fapl_id is used to + * create a new file. If \p fapl_id is used to open an existing file, + * \p memb_size has to be equal to the original size saved in file. A + * failure with an error message indicating the correct member size + * will be returned if \p memb_size does not match the size saved. If + * any user does not know the original size, #H5F_FAMILY_DEFAULT can be + * passed in. The library will retrieve the saved size. + * + * \p memb_fapl_id is the identifier of the file access property list + * to be used for each family member. + * + * \version 1.8.0 Behavior of the \p memb_size parameter was changed. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_family(hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id); + +/** + * \ingroup FAPL + * + * \brief Returns file access property list information + * + * \fapl_id + * \param[out] memb_size Size in bytes of each file member + * \param[out] memb_fapl_id Identifier of file access property list for + * each family member + * \returns \herr_t + * + * \details H5Pget_fapl_family() returns file access property list for use with + * the family driver. This information is returned through the output + * parameters. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_family(hid_t fapl_id, hsize_t *memb_size /*out*/, hid_t *memb_fapl_id /*out*/); #ifdef __cplusplus diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h index 6692ed6..af28775 100644 --- a/src/H5FDhdfs.h +++ b/src/H5FDhdfs.h @@ -111,9 +111,21 @@ typedef struct H5FD_hdfs_fapl_t { extern "C" { #endif -H5_DLL hid_t H5FD_hdfs_init(void); -H5_DLL void H5FD_hdfs_term(void); +H5_DLL hid_t H5FD_hdfs_init(void); +H5_DLL void H5FD_hdfs_term(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa); #ifdef __cplusplus diff --git a/src/H5FDlog.h b/src/H5FDlog.h index 12b654b..bb67802 100644 --- a/src/H5FDlog.h +++ b/src/H5FDlog.h @@ -60,8 +60,411 @@ extern "C" { #endif -H5_DLL hid_t H5FD_log_init(void); -H5_DLL void H5FD_log_term(void); +H5_DLL hid_t H5FD_log_init(void); +H5_DLL void H5FD_log_term(void); + +/** + * \ingroup FAPL + * + * \brief Sets up the logging virtual file driver (#H5FD_LOG) for use + * + * \fapl_id + * \param[in] logfile Name of the log file + * \param[in] flags Flags specifying the types of logging activity + * \param[in] buf_size The size of the logging buffers, in bytes (see description) + * \returns \herr_t + * + * \details H5Pset_fapl_log() modifies the file access property list to use the + * logging driver, #H5FD_LOG. The logging virtual file driver (VFD) is + * a clone of the standard SEC2 (#H5FD_SEC2) driver with additional + * facilities for logging VFD metrics and activity to a file. + * + * \p logfile is the name of the file in which the logging entries are + * to be recorded. + * + * The actions to be logged are specified in the parameter \p flags + * using the pre-defined constants described in the following + * table. Multiple flags can be set through the use of a logical \c OR + * contained in parentheses. For example, logging read and write + * locations would be specified as + * \Code{(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)}. + * + * <table> + * <caption>Table1: Logging Flags</caption> + * <tr> + * <td> + * #H5FD_LOG_LOC_READ + * </td> + * <td rowspan="3"> + * Track the location and length of every read, write, or seek operation. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_LOC_WRITE</td></tr> + * <tr><td>#H5FD_LOG_LOC_SEEK</td></tr> + * <tr> + * <td> + * #H5FD_LOG_LOC_IO + * </td> + * <td> + * Track all I/O locations and lengths. The logical equivalent of the following: + * \Code{(#H5FD_LOG_LOC_READ | #H5FD_LOG_LOC_WRITE | #H5FD_LOG_LOC_SEEK)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_FILE_READ + * </td> + * <td rowspan="2"> + * Track the number of times each byte is read or written. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_FILE_WRITE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_FILE_IO + * </td> + * <td> + * Track the number of times each byte is read and written. The logical + * equivalent of the following: + * \Code{(#H5FD_LOG_FILE_READ | #H5FD_LOG_FILE_WRITE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_FLAVOR + * </td> + * <td> + * Track the type, or flavor, of information stored at each byte. + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_NUM_READ + * </td> + * <td rowspan="4"> + * Track the total number of read, write, seek, or truncate operations that occur. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_NUM_WRITE</td></tr> + * <tr><td>#H5FD_LOG_NUM_SEEK</td></tr> + * <tr><td>#H5FD_LOG_NUM_TRUNCATE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_NUM_IO + * </td> + * <td> + * Track the total number of all types of I/O operations. The logical equivalent + * of the following: + * \Code{(#H5FD_LOG_NUM_READ | #H5FD_LOG_NUM_WRITE | #H5FD_LOG_NUM_SEEK | #H5FD_LOG_NUM_TRUNCATE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_TIME_OPEN + * </td> + * <td rowspan="6"> + * Track the time spent in open, stat, read, write, seek, or close operations. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_TIME_STAT</td></tr> + * <tr><td>#H5FD_LOG_TIME_READ</td></tr> + * <tr><td>#H5FD_LOG_TIME_WRITE</td></tr> + * <tr><td>#H5FD_LOG_TIME_SEEK</td></tr> + * <tr><td>#H5FD_LOG_TIME_CLOSE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_TIME_IO + * </td> + * <td> + * Track the time spent in each of the above operations. The logical equivalent + * of the following: + * \Code{(#H5FD_LOG_TIME_OPEN | #H5FD_LOG_TIME_STAT | #H5FD_LOG_TIME_READ | #H5FD_LOG_TIME_WRITE | + * #H5FD_LOG_TIME_SEEK | #H5FD_LOG_TIME_CLOSE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_ALLOC + * </td> + * <td> + * Track the allocation of space in the file. + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_ALL + * </td> + * <td> + * Track everything. The logical equivalent of the following: + * \Code{(#H5FD_LOG_ALLOC | #H5FD_LOG_TIME_IO | #H5FD_LOG_NUM_IO | #H5FD_LOG_FLAVOR | #H5FD_LOG_FILE_IO | + * #H5FD_LOG_LOC_IO)} + * </td> + * </tr> + * </table> + * The logging driver can track the number of times each byte in the file is + * read from or written to (using #H5FD_LOG_FILE_READ and #H5FD_LOG_FILE_WRITE) + * and what kind of data is at that location (e.g., metadata, raw data; using + * #H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size + * buf_size, which must be at least the maximum size in bytes of the file to be + * logged while the log driver is in use.\n + * One buffer of size buf_size will be created for each of #H5FD_LOG_FILE_READ, + * #H5FD_LOG_FILE_WRITE and #H5FD_LOG_FLAVOR when those flags are set; these + * buffers will not grow as the file increases in size. + * + * \par Output: + * This section describes the logging driver (LOG VFD) output.\n + * The table, immediately below, describes output of the various logging driver + * flags and function calls. A list of valid flavor values, describing the type + * of data stored, follows the table. + * <table> + * <caption>Table2: Logging Output</caption> + * <tr> + * <th>Flag</th><th>VFD Call</th><th>Output and Comments</th> + * </th> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_READ</td> + * <td>Read</td> + * <td> + * \Code{%10a-%10a (%10Zu bytes) (%s) Read}\n\n + * Start position\n + * End position\n + * Number of bytes\n + * Flavor of read\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_READ</td> + * <td>Read Error</td> + * <td> + * \Code{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n + * Same parameters as non-error entry. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_WRITE</td> + * <td>Write</td> + * <td> + * \Code{%10a-%10a (%10Zu bytes) (%s) Written}\n\n + * Start position\n + * End position\n + * Number of bytes\n + * Flavor of write\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_WRITE</td> + * <td>Write Error</td> + * <td> + * \Code{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n + * Same parameters as non-error entry. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_SEEK</td> + * <td>Read, Write</td> + * <td> + * \Code{Seek: From %10a-%10a}\n\n + * Start position\n + * End position\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FILE_READ</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping read I/O information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) read from %3d times}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Number of times read\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FILE_WRITE</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping read I/O information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) written to %3d times}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Number of times written\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FLAVOR</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping I/O flavor information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) flavor is %s}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Flavor\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_READ</td> + * <td>Close</td> + * <td> + * Total number of read operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_WRITE</td> + * <td>Close</td> + * <td> + * Total number of write operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_SEEK</td> + * <td>Close</td> + * <td> + * Total number of seek operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_TRUNCATE</td> + * <td>Close</td> + * <td> + * Total number of truncate operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_OPEN</td> + * <td>Open</td> + * <td> + * Open took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_READ</td> + * <td>Close, Read</td> + * <td> + * Total time in read operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_READ + * </td> + * </tr> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_WRITE</td> + * <td>Close, Write</td> + * <td> + * Total time in write operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_WRITE + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_SEEK</td> + * <td>Close, Read, Write</td> + * <td> + * Total time in write operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_CLOSE</td> + * <td>Close</td> + * <td> + * Close took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_STAT</td> + * <td>Open</td> + * <td> + * Stat took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_ALLOC</td> + * <td>Alloc</td> + * <td> + * \Code{%10-%10 (%10Hu bytes) (\%s) Allocated}\n\n + * Start of address space\n + * End of address space\n + * Total size allocation\n + * Flavor of allocation + * </td> + * </tr> + * </table> + * + * \par Flavors: + * The \Emph{flavor} describes the type of stored information. The following + * table lists the flavors that appear in log output and briefly describes each. + * These terms are provided here to aid in the construction of log message + * parsers; a full description is beyond the scope of this document. + * <table> + * <caption>Table3: Flavors of logged data</caption> + * <tr> + * <th>Flavor</th><th>Description</th> + * </th> + * </tr> + * <tr> + * <td>#H5FD_MEM_NOLIST</td> + * <td>Error value</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DEFAULT</td> + * <td>Value not yet set.\n + * May also be a datatype set in a larger allocation that will be + * suballocated by the library.</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_SUPER</td> + * <td>Superblock data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_BTREE</td> + * <td>B-tree data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DRAW</td> + * <td>Raw data (for example, contents of a dataset)</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_GHEAP</td> + * <td>Global heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_LHEAP</td> + * <td>Local heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_OHDR</td> + * <td>Object header data</td> + * </tr> + * </table> + * + * \version 1.8.7 The flags parameter has been changed from \Code{unsigned int} + * to \Code{unsigned long long}. + * The implementation of the #H5FD_LOG_TIME_OPEN, #H5FD_LOG_TIME_READ, + * #H5FD_LOG_TIME_WRITE, and #H5FD_LOG_TIME_SEEK flags has been finished. + * New flags were added: #H5FD_LOG_NUM_TRUNCATE and #H5FD_LOG_TIME_STAT. + * \version 1.6.0 The \c verbosity parameter has been removed. + * Two new parameters have been added: \p flags of type \Code{unsigned} and + * \p buf_size of type \Code{size_t}. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size); #ifdef __cplusplus diff --git a/src/H5FDmpi.h b/src/H5FDmpi.h index 3af5e41..cf49301 100644 --- a/src/H5FDmpi.h +++ b/src/H5FDmpi.h @@ -34,10 +34,12 @@ */ #define H5D_MULTI_CHUNK_IO_COL_THRESHOLD 60 -/* Type of I/O for data transfer properties */ +/** + * Type of I/O for data transfer properties + */ typedef enum H5FD_mpio_xfer_t { - H5FD_MPIO_INDEPENDENT = 0, /*zero is the default*/ - H5FD_MPIO_COLLECTIVE + H5FD_MPIO_INDEPENDENT = 0, /**< Use independent I/O access */ + H5FD_MPIO_COLLECTIVE /**< Use collective I/O access */ } H5FD_mpio_xfer_t; /* Type of chunked dataset I/O */ diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index 5446b77..7e40151 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -44,15 +44,238 @@ H5_DLLVAR hbool_t H5FD_mpi_opt_types_g; #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_mpio_init(void); -H5_DLL void H5FD_mpio_term(void); +H5_DLL hid_t H5FD_mpio_init(void); +H5_DLL void H5FD_mpio_term(void); + +/** + * \ingroup FAPL + * + * \brief Stores MPI IO communicator information to the file access property list + * + * \fapl_id + * \param[in] comm MPI-2 communicator + * \param[in] info MPI-2 info object + * \returns \herr_t + * + * \details H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters \p + * comm, for communicator, and \p info, for information, in the file + * access property list \p fapl_id. That property list can then be used + * to create and/or open a file. + * + * H5Pset_fapl_mpio() is available only in the parallel HDF5 library + * and is not a collective function. + * + * \p comm is the MPI communicator to be used for file open, as defined + * in \c MPI_File_open of MPI-2. This function makes a duplicate of the + * communicator, so modifications to \p comm after this function call + * returns have no effect on the file access property list. + * + * \p info is the MPI Info object to be used for file open, as defined + * in MPI_File_open() of MPI-2. This function makes a duplicate copy of + * the Info object, so modifications to the Info object after this + * function call returns will have no effect on the file access + * property list. + * + * If the file access property list already contains previously-set + * communicator and Info values, those values will be replaced and the + * old communicator and Info object will be freed. + * + * \note Raw dataset chunk caching is not currently supported when using this + * file driver in read/write mode. All calls to H5Dread() and H5Dwrite() + * will access the disk directly, and H5Pset_cache() and + * H5Pset_chunk_cache() will have no effect on performance.\n + * Raw dataset chunk caching is supported when this driver is used in + * read-only mode. + * + * \version 1.4.5 Handling of the MPI Communicator and Info object changed at + * this release. A duplicate of each of these is now stored in the property + * list instead of pointers to each. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info); + +/** + * \ingroup FAPL + * + * \brief Returns MPI IO communicator information + * + * \fapl_id + * \param[out] comm MPI-2 communicator + * \param[out] info MPI-2 info object + * \returns \herr_t + * + * \details If the file access property list is set to the #H5FD_MPIO driver, + * H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator + * and Info object through the \p comm and \p info pointers, if those + * values are non-null. + * + * Since the MPI communicator and Info object are duplicates of the + * stored information, future modifications to the access property list + * will not affect them. It is the responsibility of the application to + * free these objects. + * + * \version 1.4.5 Handling of the MPI Communicator and Info object changed at + * this release. A duplicate of each of these is now stored in the + * property list instead of pointers to each. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/); + +/** + * \ingroup DXPL + * + * \brief Sets data transfer mode + * + * \dxpl_id + * \param[in] xfer_mode Transfer mode + * \returns \herr_t + * + * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id + * to use transfer mode \p xfer_mode. The property list can then be + * used to control the I/O transfer mode during data I/O operations. + * + * Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and + * #H5FD_MPIO_COLLECTIVE. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode); + +/** + * \ingroup DXPL + * + * \brief Returns the data transfer mode + * + * \dxpl_id + * \param[out] xfer_mode Transfer mode + * \returns \herr_t + * + * \details H5Pget_dxpl_mpio() queries the data transfer mode currently set in + * the data transfer property list \p dxpl_id. + * + * Upon return, \p xfer_mode contains the data transfer mode, if it is + * non-null. + * + * H5Pget_dxpl_mpio() is not a collective function. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*/); + +/** + * \ingroup DXPL + * + * \brief Sets data transfer mode + * + * \dxpl_id + * \param[in] opt_mode Transfer mode + * \returns \herr_t + * + * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id + * to use transfer mode xfer_mode. The property list can then be used + * to control the I/O transfer mode during data I/O operations. + * + * Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and + * #H5FD_MPIO_COLLECTIVE. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode); + +/** + * \ingroup DXPL + * + * \brief Sets a flag specifying linked-chunk I/O or multi-chunk I/O + * + * \dxpl_id + * \param[in] opt_mode Transfer mode + * \returns \herr_t + * + * \details H5Pset_dxpl_mpio_chunk_opt() specifies whether I/O is to be + * performed as linked-chunk I/O or as multi-chunk I/O. This function + * overrides the HDF5 library's internal algorithm for determining + * which mechanism to use. + * + * When an application uses collective I/O with chunked storage, the + * HDF5 library normally uses an internal algorithm to determine + * whether that I/O activity should be conducted as one linked-chunk + * I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt() is provided + * so that an application can override the library's algorithm in + * circumstances where the library might lack the information needed to + * make an optimal decision. + * + * H5Pset_dxpl_mpio_chunk_opt() works by setting one of the following + * flags in the parameter \p opt_mode: + * - #H5FD_MPIO_CHUNK_ONE_IO - Do one-link chunked I/O + * - #H5FD_MPIO_CHUNK_MULTI_IO - Do multi-chunked I/O + * + * This function works by setting a corresponding property in the + * dataset transfer property list \p dxpl_id. + * + * The library performs I/O in the specified manner unless it + * determines that the low-level MPI IO package does not support the + * requested behavior; in such cases, the HDF5 library will internally + * use independent I/O. + * + * Use of this function is optional. + * + * \todo Add missing version information + * + */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); + +/** + * \ingroup DXPL + * + * \brief Sets a numeric threshold for linked-chunk I/O + * + * \dxpl_id + * \param[in] num_chunk_per_proc + * \returns \herr_t + * + * \details H5Pset_dxpl_mpio_chunk_opt_num() sets a numeric threshold for the + * use of linked-chunk I/O. + * + * The library will calculate the average number of chunks selected by + * each process when doing collective access with chunked storage. If + * the number is greater than the threshold set in \p + * num_chunk_per_proc, the library will use linked-chunk I/O; + * otherwise, a separate I/O process will be invoked for each chunk + * (multi-chunk I/O). + * + * \todo Add missing version information + * + */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); + +/** + * \ingroup DXPL + * + * \brief Sets a ratio threshold for collective I/O + * + * \dxpl_id + * \param[in] percent_num_proc_per_chunk + * \returns \herr_t + * + * \details H5Pset_dxpl_mpio_chunk_opt_ratio() sets a threshold for the use of + * collective I/O based on the ratio of processes with collective + * access to a dataset with chunked storage. The decision whether to + * use collective I/O is made on a per-chunk basis. + * + * The library will calculate the percentage of the total number of + * processes, the ratio, that hold selections in each chunk. If that + * percentage is greater than the threshold set in \p + * percent_proc_per_chunk, the library will do collective I/O for this + * chunk; otherwise, independent I/O will be done for the chunk. + * + * \todo Add missing version information + * + */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); #ifdef __cplusplus } diff --git a/src/H5FDmulti.h b/src/H5FDmulti.h index 8a3fb79..85c2fb6 100644 --- a/src/H5FDmulti.h +++ b/src/H5FDmulti.h @@ -25,12 +25,229 @@ #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_multi_init(void); -H5_DLL void H5FD_multi_term(void); +H5_DLL hid_t H5FD_multi_init(void); +H5_DLL void H5FD_multi_term(void); + +/** + * \ingroup FAPL + * + * \brief Sets up use of the multi-file driver + * + * \fapl_id + * \param[in] memb_map Maps memory usage types to other memory usage types + * \param[in] memb_fapl Property list for each memory usage type + * \param[in] memb_name Name generator for names of member files + * \param[in] memb_addr The offsets within the virtual address space, from 0 + * (zero) to #HADDR_MAX, at which each type of data storage begins + * \param[in] relax Allows read-only access to incomplete file sets when \c TRUE + * \returns \herr_t + * + * \details H5Pset_fapl_multi() sets the file access property list \p fapl_id to + * use the multi-file driver. + * + * The multi-file driver enables different types of HDF5 data and + * metadata to be written to separate files. These files are viewed by + * the HDF5 library and the application as a single virtual HDF5 file + * with a single HDF5 file address space. The types of data that can be + * broken out into separate files include raw data, the superblock, + * B-tree data, global heap data, local heap data, and object + * headers. At the programmer's discretion, two or more types of data + * can be written to the same file while other types of data are + * written to separate files. + * + * The array \p memb_map maps memory usage types to other memory usage + * types and is the mechanism that allows the caller to specify how + * many files are created. The array contains #H5FD_MEM_NTYPES entries, + * which are either the value #H5FD_MEM_DEFAULT or a memory usage + * type. The number of unique values determines the number of files + * that are opened. + * + * The array \p memb_fapl contains a property list for each memory + * usage type that will be associated with a file. + * + * The array \p memb_name should be a name generator (a + * \Code{printf}-style format with a \Code{%s} which will be replaced + * with the name passed to H5FDopen(), usually from H5Fcreate() or + * H5Fopen()). + * + * The array \p memb_addr specifies the offsets within the virtual + * address space, from 0 (zero) to #HADDR_MAX, at which each type of + * data storage begins. + * + * If \p relax is set to 1 (TRUE), then opening an existing file for + * read-only access will not fail if some file members are + * missing. This allows a file to be accessed in a limited sense if + * just the meta data is available. + * + * Default values for each of the optional arguments are as follows: + * <table> + * <tr> + * <td>\p memb_map</td> + * <td>The default member map contains the value #H5FD_MEM_DEFAULT for each element.</td> + * </tr> + * <tr> + * <td> + * \p memb_fapl + * </td> + * <td> + * The default value is #H5P_DEFAULT for each element. + * </td> + * </tr> + * <tr> + * <td> + * \p memb_name + * </td> + * <td> + * The default string is \Code{%s-X.h5} where \c X is one of the following letters: + * - \c s for #H5FD_MEM_SUPER + * - \c b for #H5FD_MEM_BTREE + * - \c r for #H5FD_MEM_DRAW + * - \c g for #H5FD_MEM_GHEAP + * - \c l for #H5FD_MEM_LHEAP + * - \c o for #H5FD_MEM_OHDR + * </td> + * </tr> + * <tr> + * <td> + * \p memb_addr + * </td> + * <td> + * The default setting is that the address space is equally divided + * among all of the elements: + * - #H5FD_MEM_SUPER \Code{-> 0 * (HADDR_MAX/6)} + * - #H5FD_MEM_BTREE \Code{-> 1 * (HADDR_MAX/6)} + * - #H5FD_MEM_DRAW \Code{-> 2 * (HADDR_MAX/6)} + * - #H5FD_MEM_GHEAP \Code{-> 3 * (HADDR_MAX/6)} + * - #H5FD_MEM_LHEAP \Code{-> 4 * (HADDR_MAX/6)} + * - #H5FD_MEM_OHDR \Code{-> 5 * (HADDR_MAX/6)} + * </td> + * </tr> + * </table> + * + * \par Example: + * The following code sample sets up a multi-file access property list that + * partitions data into meta and raw files, each being one-half of the address:\n + * \code + * H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES]; + * hid_t memb_fapl[H5FD_MEM_NTYPES]; + * const char *memb[H5FD_MEM_NTYPES]; + * haddr_t memb_addr[H5FD_MEM_NTYPES]; + * + * // The mapping... + * for (mt=0; mt<H5FD_MEM_NTYPES; mt++) { + * memb_map[mt] = H5FD_MEM_SUPER; + * } + * memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW; + * + * // Member information + * memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT; + * memb_name[H5FD_MEM_SUPER] = "%s.meta"; + * memb_addr[H5FD_MEM_SUPER] = 0; + * + * memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT; + * memb_name[H5FD_MEM_DRAW] = "%s.raw"; + * memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2; + * + * hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_multi(fapl, memb_map, memb_fapl, + * memb_name, memb_addr, TRUE); + * \endcode + * + * \version 1.6.3 \p memb_name parameter type changed to \Code{const char* const*}. + * \since 1.4.0 + */ H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax); + +/** + * \ingroup FAPL + * + * \brief Returns information about the multi-file access property list + * + * \fapl_id + * \param[out] memb_map Maps memory usage types to other memory usage types + * \param[out] memb_fapl Property list for each memory usage type + * \param[out] memb_name Name generator for names of member files + * \param[out] memb_addr The offsets within the virtual address space, from 0 + * (zero) to #HADDR_MAX, at which each type of data storage begins + * \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 + * property list. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid_t *memb_fapl /*out*/, char **memb_name /*out*/, haddr_t *memb_addr /*out*/, hbool_t *relax /*out*/); + +/** + * \ingroup FAPL + * + * \brief Emulates the old split file driver + * + * \fapl_id{fapl} + * \param[in] meta_ext Metadata filename extension + * \param[in] meta_plist_id File access property list identifier for the metadata file + * \param[in] raw_ext Raw data filename extension + * \param[in] raw_plist_id + * \returns \herr_t + * + * \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 + * metadata. + * + * \p fapl is a file access property list identifier. + * + * \p meta_ext is the filename extension for the metadata file. The + * extension is appended to the name passed to H5FDopen(), usually from + * H5Fcreate() or H5Fopen(), to form the name of the metadata file. If + * the string \Code{%s} is used in the extension, it works like the + * name generator as in H5Pset_fapl_multi(). + * + * \p meta_plist_id is the file access property list identifier for the + * metadata file. + * + * \p raw_ext is the filename extension for the raw data file. The + * extension is appended to the name passed to H5FDopen(), usually from + * H5Fcreate() or H5Fopen(), to form the name of the raw data file. If + * the string \Code{%s} is used in the extension, it works like the + * name generator as in H5Pset_fapl_multi(). + * + * \p raw_plist_id is the file access property list identifier for the + * raw data file. + * + * If a user wishes to check to see whether this driver is in use, the + * user must call H5Pget_driver() and compare the returned value to the + * string #H5FD_MULTI. A positive match will confirm that the multi + * driver is in use; HDF5 provides no mechanism to determine whether it + * was called as the special case invoked by H5Pset_fapl_split(). + * + * \par Example: + * \code + * // Example 1: Both metadata and rawdata files are in the same + * // directory. Use Station1-m.h5 and Station1-r.h5 as + * // the metadata and rawdata files. + * hid_t fapl, fid; + * fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT); + * fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); + * + * // Example 2: metadata and rawdata files are in different + * // directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as + * // the metadata and rawdata files. + * hid_t fapl, fid; + * fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT); + * fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); + * \endcode + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id); #ifdef __cplusplus diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h index 8b3198f..ff0f54a9 100644 --- a/src/H5FDpublic.h +++ b/src/H5FDpublic.h @@ -265,29 +265,113 @@ struct H5FD_t { hsize_t alignment; /* Allocation alignment */ }; -/* Define enum for the source of file image callbacks */ +/** + * Define enum for the source of file image callbacks + */ +//! <!-- [H5FD_file_image_op_t_snip] --> typedef enum { H5FD_FILE_IMAGE_OP_NO_OP, H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks when a + * file image buffer is to be copied while being set in a file access + * property list (FAPL)*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks + * when a file image buffer is to be copied when a FAPL is copied*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET, + /**<Passed to the \p image_malloc and \p image_memcpy callbacks when + * a file image buffer is to be copied while being retrieved from a FAPL*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, + /**<Passed to the \p image_free callback when a file image + * buffer is to be released during a FAPL close operation*/ H5FD_FILE_IMAGE_OP_FILE_OPEN, + /**<Passed to the \p image_malloc and + * \p image_memcpy callbackswhen a + * file image buffer is to be copied during a file open operation \n + * While the file image being opened will typically be copied from a + * FAPL, this need not always be the case. For example, the core file + * driver, also known as the memory file driver, takes its initial + * image from a file.*/ H5FD_FILE_IMAGE_OP_FILE_RESIZE, + /**<Passed to the \p image_realloc callback when a file driver needs + * to resize an image buffer*/ H5FD_FILE_IMAGE_OP_FILE_CLOSE + /**<Passed to the \p image_free callback when an image buffer is to + * be released during a file close operation*/ } H5FD_file_image_op_t; +//! <!-- [H5FD_file_image_op_t_snip] --> -/* Define structure to hold file image callbacks */ +/** + * Define structure to hold file image callbacks + */ +//! <!-- [H5FD_file_image_callbacks_t_snip] --> typedef struct { + /** + * \param[in] size Size in bytes of the file image buffer to allocate + * \param[in] file_image_op A value from H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_malloc_snip] --> void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_malloc_snip] --> + /** + * \param[in] dest Address of the destination buffer + * \param[in] src Address of the source buffer + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_memcpy_snip] --> void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_memcpy_snip] --> + /** + * \param[in] ptr Pointer to the buffer being reallocated + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_realloc_snip] --> void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_realloc_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_free_snip] --> herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_free_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_copy_snip] --> void *(*udata_copy)(void *udata); + //! <!-- [udata_copy_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_free_snip] --> herr_t (*udata_free)(void *udata); + //! <!-- [udata_free_snip] --> + /** + * \brief The final field in the #H5FD_file_image_callbacks_t struct, + * provides a pointer to user-defined data. This pointer will be + * passed to the image_malloc, image_memcpy, image_realloc, and + * image_free callbacks. Define udata as NULL if no user-defined + * data is provided. + */ void *udata; } H5FD_file_image_callbacks_t; +//! <!-- [H5FD_file_image_callbacks_t_snip] --> #ifdef __cplusplus extern "C" { diff --git a/src/H5FDros3.h b/src/H5FDros3.h index 57a7597..7cf48c1 100644 --- a/src/H5FDros3.h +++ b/src/H5FDros3.h @@ -89,9 +89,21 @@ typedef struct H5FD_ros3_fapl_t { extern "C" { #endif -H5_DLL hid_t H5FD_ros3_init(void); -H5_DLL void H5FD_ros3_term(void); +H5_DLL hid_t H5FD_ros3_init(void); +H5_DLL void H5FD_ros3_term(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa); #ifdef __cplusplus diff --git a/src/H5FDstdio.h b/src/H5FDstdio.h index 2ad4352..5f3b1d0 100644 --- a/src/H5FDstdio.h +++ b/src/H5FDstdio.h @@ -28,8 +28,23 @@ extern "C" { #endif -H5_DLL hid_t H5FD_stdio_init(void); -H5_DLL void H5FD_stdio_term(void); +H5_DLL hid_t H5FD_stdio_init(void); +H5_DLL void H5FD_stdio_term(void); + +/** + * \ingroup FAPL + * + * \brief Sets the standard I/O driver + * + * \fapl_id + * \returns \herr_t + * + * \details H5Pset_fapl_stdio() modifies the file access property list to use + * the standard I/O driver, H5FDstdio(). + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_stdio(hid_t fapl_id); #ifdef __cplusplus diff --git a/src/H5FDwindows.h b/src/H5FDwindows.h index 2060440..07fecf4 100644 --- a/src/H5FDwindows.h +++ b/src/H5FDwindows.h @@ -28,13 +28,37 @@ #ifdef __cplusplus extern "C" { -#endif +#endif /* __cplusplus */ -/* The code behind the windows VFD has been removed and the windows - * VFD initialization has been redirected to the SEC2 driver. The - * "Windows" VFD was actually identical to the SEC2 driver code - * (a planned Win32 API driver never happened) so this change - * should be transparent to users. +/** + * \ingroup FAPL + * + * \brief Sets the Windows I/O driver + * + * \fapl_id + * \returns \herr_t + * + * \details H5Pset_fapl_windows() sets the default HDF5 Windows I/O driver on + * Windows systems. + * + * Since the HDF5 library uses this driver, #H5FD_WINDOWS, by default + * on Windows systems, it is not normally necessary for a user + * application to call H5Pset_fapl_windows(). While it is not + * recommended, there may be times when a user chooses to set a + * different HDF5 driver, such as the standard I/O driver (#H5FD_STDIO) + * or the sec2 driver (#H5FD_SEC2), in a Windows + * application. H5Pset_fapl_windows() is provided so that the + * application can return to the Windows I/O driver when the time + * comes. + * + * Only the Windows driver is tested on Windows systems; other drivers + * are used at the application’s and the user’s risk. + * + * Furthermore, the Windows driver is tested and available only on + * Windows systems; it is not available on non-Windows systems. + * + * \since 1.8.0 + * */ #define H5FD_windows_init H5FD_sec2_init #define H5FD_windows_term H5FD_sec2_term @@ -42,6 +66,6 @@ H5_DLL herr_t H5Pset_fapl_windows(hid_t fapl_id); #ifdef __cplusplus } -#endif +#endif /* __cplusplus */ -#endif +#endif /* H5FDwindows_H */ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 574bf87..806320b 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -42,31 +42,36 @@ * H5F_ACC_DEBUG no longer has any prints any special debug info. The symbol is * being retained and will be listed as deprecated in HDF5 1.10.0. */ -#define H5F_ACC_RDONLY (H5CHECK 0x0000u) /*absence of rdwr => rd-only */ -#define H5F_ACC_RDWR (H5CHECK 0x0001u) /*open for read and write */ -#define H5F_ACC_TRUNC (H5CHECK 0x0002u) /*overwrite existing files */ -#define H5F_ACC_EXCL (H5CHECK 0x0004u) /*fail if file already exists */ -#define H5F_ACC_DEBUG (H5CHECK 0x0000u) /*print debug info (no longer used) */ -#define H5F_ACC_CREAT (H5CHECK 0x0010u) /*create non-existing files */ +#define H5F_ACC_RDONLY (H5CHECK 0x0000u) /**< Absence of RDWR: read-only */ +#define H5F_ACC_RDWR (H5CHECK 0x0001u) /**< Open for read and write */ +#define H5F_ACC_TRUNC (H5CHECK 0x0002u) /**< Overwrite existing files */ +#define H5F_ACC_EXCL (H5CHECK 0x0004u) /**< Fail if file already exists*/ +#define H5F_ACC_DEBUG (H5CHECK 0x0000u) /**< print debug info (no longer used) */ +#define H5F_ACC_CREAT (H5CHECK 0x0010u) /**< create non-existing files */ -/* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the - * parent file. */ -#define H5F_ACC_DEFAULT (H5CHECK 0xffffu) /*ignore setting on lapl */ +/** + * Default property list identifier + * + * \internal Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the parent file. + * \internal ignore setting on lapl + */ +#define H5F_ACC_DEFAULT (H5CHECK 0xffffu) /* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */ -#define H5F_OBJ_FILE (0x0001u) /* File objects */ -#define H5F_OBJ_DATASET (0x0002u) /* Dataset objects */ -#define H5F_OBJ_GROUP (0x0004u) /* Group objects */ -#define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */ -#define H5F_OBJ_ATTR (0x0010u) /* Attribute objects */ +#define H5F_OBJ_FILE (0x0001u) /**< File objects */ +#define H5F_OBJ_DATASET (0x0002u) /**< Dataset objects */ +#define H5F_OBJ_GROUP (0x0004u) /**< Group objects */ +#define H5F_OBJ_DATATYPE (0x0008u) /**< Named datatype objects */ +#define H5F_OBJ_ATTR (0x0010u) /**< Attribute objects */ #define H5F_OBJ_ALL (H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR) -#define H5F_OBJ_LOCAL (0x0020u) /* Restrict search to objects opened through current file ID */ -/* (as opposed to objects opened through any file ID accessing this file) */ +#define H5F_OBJ_LOCAL \ + (0x0020u) /**< Restrict search to objects opened through current file ID \ + (as opposed to objects opened through any file ID accessing this file) */ #define H5F_FAMILY_DEFAULT (hsize_t)0 #ifdef H5_HAVE_PARALLEL -/* +/** * Use this constant string as the MPI_Info key to set H5Fmpio debug flags. * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to * have the value of a string consisting of the characters that turn on the @@ -75,71 +80,76 @@ #define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key" #endif /* H5_HAVE_PARALLEL */ -/* The difference between a single file and a set of mounted files */ +/** + * The scope of an operation such as H5Fflush(), e.g., + * a single file vs. a set of mounted files + */ typedef enum H5F_scope_t { - H5F_SCOPE_LOCAL = 0, /*specified file handle only */ - H5F_SCOPE_GLOBAL = 1 /*entire virtual file */ + H5F_SCOPE_LOCAL = 0, /**< The specified file handle only */ + H5F_SCOPE_GLOBAL = 1 /**< The entire virtual file */ } H5F_scope_t; -/* Unlimited file size for H5Pset_external() */ +/** + * Unlimited file size for H5Pset_external() + */ #define H5F_UNLIMITED ((hsize_t)(-1L)) -/* How does file close behave? - * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL - * H5F_CLOSE_WEAK - file closes only after all opened objects are closed - * H5F_CLOSE_SEMI - if no opened objects, file is close; otherwise, file - close fails - * H5F_CLOSE_STRONG - if there are opened objects, close them first, then - close file +/** + * How does file close behave? */ typedef enum H5F_close_degree_t { - H5F_CLOSE_DEFAULT = 0, - H5F_CLOSE_WEAK = 1, - H5F_CLOSE_SEMI = 2, - H5F_CLOSE_STRONG = 3 + H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlying VFD */ + H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */ + H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is closed; otherwise, file close fails */ + H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */ } H5F_close_degree_t; -/* Current "global" information about file */ -/* (just size info currently) */ +/** + * Current "global" information about file + */ +//! <!-- [H5F_info_t_snip] --> typedef struct H5F_info_t { - hsize_t super_ext_size; /* Superblock extension size */ + hsize_t super_ext_size; /**< Superblock extension size */ struct { - hsize_t hdr_size; /* Shared object header message header size */ - H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ + hsize_t hdr_size; /**< Shared object header message header size */ + H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info_t; +//! <!-- [H5F_info_t_snip] --> -/* - * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT +/** + * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT * should not change other than adding new types to the end. These numbers * might appear in files. * - * Note: please change the log VFD flavors array if you change this - * enumeration. + * \internal Please change the log VFD flavors array if you change this + * enumeration. */ typedef enum H5F_mem_t { - H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list. + H5FD_MEM_NOLIST = -1, /**< Data should not appear in the free list. * Must be negative. */ - H5FD_MEM_DEFAULT = 0, /* Value not yet set. Can also be the + H5FD_MEM_DEFAULT = 0, /**< Value not yet set. Can also be the * datatype set in a larger allocation * that will be suballocated by the library. * Must be zero. */ - H5FD_MEM_SUPER = 1, /* Superblock data */ - H5FD_MEM_BTREE = 2, /* B-tree data */ - H5FD_MEM_DRAW = 3, /* Raw data (content of datasets, etc.) */ - H5FD_MEM_GHEAP = 4, /* Global heap data */ - H5FD_MEM_LHEAP = 5, /* Local heap data */ - H5FD_MEM_OHDR = 6, /* Object header data */ - - H5FD_MEM_NTYPES /* Sentinel value - must be last */ + H5FD_MEM_SUPER = 1, /**< Superblock data */ + H5FD_MEM_BTREE = 2, /**< B-tree data */ + H5FD_MEM_DRAW = 3, /**< Raw data (content of datasets, etc.) */ + H5FD_MEM_GHEAP = 4, /**< Global heap data */ + H5FD_MEM_LHEAP = 5, /**< Local heap data */ + H5FD_MEM_OHDR = 6, /**< Object header data */ + + H5FD_MEM_NTYPES /**< Sentinel value - must be last */ } H5F_mem_t; -/* Library's file format versions */ +/** + * Library's format versions + */ typedef enum H5F_libver_t { - H5F_LIBVER_EARLIEST, /* Use the earliest possible format for storing objects */ - H5F_LIBVER_LATEST /* Use the latest possible format available for storing objects*/ + H5F_LIBVER_EARLIEST, /**< Use the earliest possible format for storing objects */ + H5F_LIBVER_LATEST /**< Use the latest possible format available for storing objects*/ } H5F_libver_t; /* Define file format version for 1.8 to prepare for 1.10 release. @@ -150,35 +160,919 @@ typedef enum H5F_libver_t { extern "C" { #endif -/* Functions in H5F.c */ -H5_DLL htri_t H5Fis_hdf5(const char *filename); -H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t create_plist, hid_t access_plist); -H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t access_plist); -H5_DLL hid_t H5Freopen(hid_t file_id); -H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); -H5_DLL herr_t H5Fclose(hid_t file_id); -H5_DLL hid_t H5Fget_create_plist(hid_t file_id); -H5_DLL hid_t H5Fget_access_plist(hid_t file_id); -H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); -H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); -H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); -H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); -H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); -H5_DLL herr_t H5Funmount(hid_t loc, const char *name); +/** + * \ingroup H5F + * + * \brief Checks if a file can be opened with a given file access property + * list + * + * \param[in] filename Name of a file + * + * \return \htri_t + * + * \details H5F__is_hdf5() checks if the file specified by \p + * filename can be opened. + * + * \note The H5Fis_hdf5(), only uses + * the default file driver when opening a file. + * + */ +H5_DLL htri_t H5Fis_hdf5(const char *filename); +/** + * \ingroup H5F + * + * \brief Creates an HDF5 file + * + * \param[in] filename Name of the file to create + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_TRUNC: Truncate file, if it already exists, + * erasing all data previously stored in the file + * - #H5F_ACC_EXCL: Fail if file already exists + * \fcpl_id + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fcreate() is the primary function for creating HDF5 files; it + * creates a new HDF5 file with the specified name and property lists. + * + * The \p filename parameter specifies the name of the new file. + * + * The \p flags parameter specifies whether an existing file is to be + * overwritten. It should be set to either #H5F_ACC_TRUNC to overwrite + * an existing file or #H5F_ACC_EXCL, instructing the function to fail + * if the file already exists. + * + * New files are always created in read-write mode, so the read-write + * and read-only flags, #H5F_ACC_RDWR and #H5F_ACC_RDONLY, + * respectively, are not relevant in this function. Further note that + * a specification of #H5F_ACC_RDONLY will be ignored; the file will + * be created in read-write mode, regardless. + * + * More complex behaviors of file creation and access are controlled + * through the file creation and file access property lists, + * \p fcpl_id and \p fapl_id, respectively. The value of #H5P_DEFAULT + * for any property list value indicates that the library should use + * the default values for that appropriate property list. + * + * The return value is a file identifier for the newly-created file; + * this file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \par Example + * \snippet H5F_examples.c minimal + * + * \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use + * exactly one. + * + * \note An additional flag, #H5F_ACC_DEBUG, prints debug information. This + * flag can be combined with one of the above values using the bit-wise + * OR operator (\c |), but it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported for use in applications}. + * + * \attention \Bold{Special case — File creation in the case of an already-open file:} + * If a file being created is already opened, by either a previous + * H5Fopen() or H5Fcreate() call, the HDF5 library may or may not + * detect that the open file and the new file are the same physical + * file. (See H5Fopen() regarding the limitations in detecting the + * re-opening of an already-open file.)\n + * If the library detects that the file is already opened, + * H5Fcreate() will return a failure, regardless of the use of + * #H5F_ACC_TRUNC.\n + * If the library does not detect that the file is already opened + * and #H5F_ACC_TRUNC is not used, H5Fcreate() will return a failure + * because the file already exists. Note that this is correct + * behavior.\n + * But if the library does not detect that the file is already + * opened and #H5F_ACC_TRUNC is used, H5Fcreate() will truncate the + * existing file and return a valid file identifier. Such a + * truncation of a currently-opened file will almost certainly + * result in errors. While unlikely, the HDF5 library may not be + * able to detect, and thus report, such errors.\n + * Applications should avoid calling H5Fcreate() with an already + * opened file. + * + * \since 1.0.0 + * + * \see H5Fopen(), H5Fclose() + * + */ +H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Opens an existing HDF5 file + * + * \param[in] filename Name of the file to be opened + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_RDWR: Allows read and write access to file + * - #H5F_ACC_RDONLY: Allows read-only access to file + * - #H5F_ACC_RDWR \c | #H5F_ACC_SWMR_WRITE: Indicates that + * the file is open for writing in a + * single-writer/multi-writer (SWMR) scenario. + * - #H5F_ACC_RDONLY \c | #H5F_ACC_SWMR_READ: Indicates + * that the file is open for reading in a + * single-writer/multi-reader (SWMR) scenario. + * - An additional flag, #H5F_ACC_DEBUG, prints debug + * information. This flag can be combined with one of the + * above values using the bit-wise OR operator (\c |), but + * it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported} for use in + * applications. + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fopen() is the primary function for accessing existing HDF5 files. + * This function opens the named file in the specified access mode and + * with the specified access property list. + * + * Note that H5Fopen() does not create a file if it does not already + * exist; see H5Fcreate(). + * + * The \p filename parameter specifies the name of the file to be + * opened. + * + * The \p fapl_id parameter specifies the file access property list. + * Use of #H5P_DEFAULT specifies that default I/O access properties + * are to be used. + * + * The \p flags parameter specifies whether the file will be opened in + * read-write or read-only mode, #H5F_ACC_RDWR or #H5F_ACC_RDONLY, + * respectively. More complex behaviors of file access are controlled + * through the file-access property list. + * + * The return value is a file identifier for the open file; this file + * identifier should be closed by calling H5Fclose() when it is no + * longer needed. + * + * \par Example + * \snippet H5F_examples.c open + * + * \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use + * exactly one. + * + * \attention \Bold{Special cases — Multiple opens:} A file can often be opened + * with a new H5Fopen() call without closing an already-open + * identifier established in a previous H5Fopen() or H5Fcreate() + * call. Each such H5Fopen() call will return a unique identifier + * and the file can be accessed through any of these identifiers as + * long as the identifier remains valid. In such multiply-opened + * cases, the open calls must use the same flags argument and the + * file access property lists must use the same file close degree + * property setting (see the external link discussion below and + * H5Pset_fclose_degree()).\n + * In some cases, such as files on a local Unix file system, the + * HDF5 library can detect that a file is multiply opened and will + * maintain coherent access among the file identifiers.\n + * But in many other cases, such as parallel file systems or + * networked file systems, it is not always possible to detect + * multiple opens of the same physical file. In such cases, HDF5 + * will treat the file identifiers as though they are accessing + * different files and will be unable to maintain coherent access. + * Errors are likely to result in these cases. While unlikely, the + * HDF5 library may not be able to detect, and thus report, + * such errors.\n + * It is generally recommended that applications avoid multiple + * opens of the same file. + * + * \attention \Bold{Special restriction on multiple opens of a file first + * opened by means of an external link:} When an external link is + * followed, the external file is always opened with the weak file + * close degree property setting, #H5F_CLOSE_WEAK (see + * H5Lcreate_external() and H5Pset_fclose_degree()). If the file is + * reopened with H5Fopen while it remains held open from such an + * external link call, the file access property list used in the + * open call must include the file close degree setting + * #H5F_CLOSE_WEAK or the open will fail. + * + * \version 1.10.0 The #H5F_ACC_SWMR_WRITE and #H5F_ACC_SWMR_READ flags were added. + * + * \see H5Fclose() + * + */ +H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Returns a new identifier for a previously-opened HDF5 file + * + * \param[in] file_id Identifier of a file for which an additional identifier + * is required + * + * \return \hid_t{file} + * + * \details H5Freopen() returns a new file identifier for an already-open HDF5 + * file, as specified by \p file_id. Both identifiers share caches and + * other information. The only difference between the identifiers is + * that the new identifier is not mounted anywhere and no files are + * mounted on it. + * + * The new file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \note Note that there is no circumstance under which H5Freopen() can + * actually open a closed file; the file must already be open and have an + * active \p file_id. E.g., one cannot close a file with H5Fclose() on + * \p file_id then use H5Freopen() on \p file_id to reopen it. + * + */ +H5_DLL hid_t H5Freopen(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Flushes all buffers associated with a file to storage + * + * \loc_id{object_id} + * \param[in] scope The scope of the flush action + * + * \return \herr_t + * + * \details H5Fflush() causes all buffers associated with a file to be + * immediately flushed to storage without removing the data from the + * cache. + * + * \p object_id can be any object associated with the file, including + * the file itself, a dataset, a group, an attribute, or a named + * datatype. + * + * \p scope specifies whether the scope of the flush action is + * global or local. Valid values are as follows: + * \scopes + * + * \par Example + * \snippet H5F_examples.c flush + * + * \attention HDF5 does not possess full control over buffering. H5Fflush() + * flushes the internal HDF5 buffers then asks the operating system + * (the OS) to flush the system buffers for the open files. After + * that, the OS is responsible for ensuring that the data is + * actually flushed to disk. + * + */ +H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); +/** + * \ingroup H5F + * + * \brief Terminates access to an HDF5 file + * + * \file_id + * \return \herr_t + * + * \details H5Fclose() terminates access to an HDF5 file (specified by + * \p file_id) by flushing all data to storage. + * + * If this is the last file identifier open for the file and no other + * access identifier is open (e.g., a dataset identifier, group + * identifier, or shared datatype identifier), the file will be fully + * closed and access will end. + * + * \par Example + * \snippet H5F_examples.c minimal + * + * \note \Bold{Delayed close:} Note the following deviation from the + * above-described behavior. If H5Fclose() is called for a file but one + * or more objects within the file remain open, those objects will remain + * accessible until they are individually closed. Thus, if the dataset + * \c data_sample is open when H5Fclose() is called for the file + * containing it, \c data_sample will remain open and accessible + * (including writable) until it is explicitly closed. The file will be + * automatically closed once all objects in the file have been closed.\n + * Be warned, however, that there are circumstances where it is not + * possible to delay closing a file. For example, an MPI-IO file close is + * a collective call; all of the processes that opened the file must + * close it collectively. The file cannot be closed at some time in the + * future by each process in an independent fashion. Another example is + * that an application using an AFS token-based file access privilege may + * destroy its AFS token after H5Fclose() has returned successfully. This + * would make any future access to the file, or any object within it, + * illegal.\n + * In such situations, applications must close all open objects in a file + * before calling H5Fclose. It is generally recommended to do so in all + * cases. + * + * \see H5Fopen() + * + */ +H5_DLL herr_t H5Fclose(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns a file creation property list identifier + * + * \file_id + * \return \hid_t{file creation property list} + * + * \details H5Fget_create_plist() returns the file creation property list + * identifier identifying the creation properties used to create this + * file. This function is useful for duplicating properties when + * creating another file. + * + * The creation property list identifier should be released with + * H5Pclose(). + * + */ +H5_DLL hid_t H5Fget_create_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns a file access property list identifier + * + * \file_id + * \return \hid_t{file access property list} + * + * \details H5Fget_access_plist() returns the file access property list + * identifier of the specified file. + * + */ +H5_DLL hid_t H5Fget_access_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Determines the read/write or read-only status of a file + * + * \file_id + * \param[out] intent Access mode flag as originally passed with H5Fopen() + * + * \return \herr_t + * + * \details Given the identifier of an open file, \p file_id, H5Fget_intent() + * retrieves the intended access mode" flag passed with H5Fopen() when + * the file was opened. + * + * The value of the flag is returned in \p intent. Valid values are as + * follows: + * \file_access + * + * \note The function will not return an error if intent is NULL; it will + * simply do nothing. + * + * \version 1.10.0 Function enhanced to work with SWMR functionality. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); +/** + * \ingroup H5F + * + * \brief Returns the number of open object identifiers for an open file + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * + * \return Returns the number of open objects if successful; otherwise returns + * a negative value. + * + * \details Given the identifier of an open file, file_id, and the desired + * object types, types, H5Fget_obj_count() returns the number of open + * object identifiers for the file. + * + * To retrieve a count of open identifiers for open objects in all + * HDF5 application files that are currently open, pass the value + * #H5F_OBJ_ALL in \p file_id. + * + * The types of objects to be counted are specified in types as + * follows: + * \obj_types + * + * Multiple object types can be combined with the + * logical \c OR operator (|). For example, the expression + * \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and + * groups. + * + * \version 1.6.8, 1.8.2 Function return type changed to \c ssize_t. + * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types + * of objects to be counted. #H5F_OBJ_LOCAL restricts the + * search to objects opened through current file identifier. + * + */ +H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); +/** + *------------------------------------------------------------------------- + * \ingroup H5F + * + * \brief Returns a list of open object identifiers + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * \param[in] max_objs Maximum number of object identifiers to place into + * \p obj_id_list + * \param[out] obj_id_list Pointer to the returned buffer of open object + * identifiers + * + * \return Returns number of objects placed into \p obj_id_list if successful; + * otherwise returns a negative value. + * + * \details Given the file identifier \p file_id and the type of objects to be + * identified, types, H5Fget_obj_ids() returns the list of identifiers + * for all open HDF5 objects fitting the specified criteria. + * + * To retrieve identifiers for open objects in all HDF5 application + * files that are currently open, pass the value #H5F_OBJ_ALL in + * \p file_id. + * + * The types of object identifiers to be retrieved are specified in + * types using the codes listed for the same parameter in + * H5Fget_obj_count(). + * + * To retrieve a count of open objects, use the H5Fget_obj_count() + * function. This count can be used to set the \p max_objs parameter. + * + * \version 1.8.2 Function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \version 1.6.8 Function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); +/** + * \ingroup H5F + * + * \brief Returns pointer to the file handle from the virtual file driver + * + * \file_id + * \fapl_id{fapl} + * \param[out] file_handle Pointer to the file handle being used by the + * low-level virtual file driver + * + * \return \herr_t + * + * \details Given the file identifier \p file_id and the file access property + * list \p fapl_id, H5Fget_vfd_handle() returns a pointer to the file + * handle from the low-level file driver currently being used by the + * HDF5 library for file I/O. + * + * \note For most drivers, the value of \p fapl_id will be #H5P_DEFAULT. For + * the \c FAMILY or \c MULTI drivers, this value should be defined + * through the property list functions: H5Pset_family_offset() for the + * \c FAMILY driver and H5Pset_multi_type() for the \c MULTI driver + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); +/** + * \ingroup H5F + * + * \brief Mounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the group onto which the file specified by \p child + * is to be mounted + * \file_id{child} + * \param[in] plist File mount property list identifier. Pass #H5P_DEFAULT! + * + * \return \herr_t + * + * \details H5Fmount() mounts the file specified by \p child onto the object + * specified by \p loc and \p name using the mount properties \p plist + * If the object specified by \p loc is a dataset, named datatype or + * attribute, then the file will be mounted at the location where the + * attribute, dataset, or named datatype is attached. + * + * \par Example + * \snippet H5F_examples.c mount + * + * \note To date, no file mount properties have been defined in HDF5. The + * proper value to pass for \p plist is #H5P_DEFAULT, indicating the + * default file mount property list. + * + */ +H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); +/** + * \ingroup H5F + * + * \brief Unounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the mount point + * + * \return \herr_t + * + * \details Given a mount point, H5Funmount() dissociates the mount point's + * file from the file mounted there. This function does not close + * either file. + * + * The mount point can be either the group in the parent or the root + * group of the mounted file (both groups have the same name). If the + * mount point was opened before the mount then it is the group in the + * parent; if it was opened after the mount then it is the root group + * of the child. + * + */ +H5_DLL herr_t H5Funmount(hid_t loc, const char *name); +/** + * \ingroup H5F + * + * \brief Returns the amount of free space in a file (in bytes) + * + * \file_id + * + * \return Returns the amount of free space in the file if successful; + * otherwise returns a negative value. + * + * \details Given the identifier of an open file, \p file_id, + * H5Fget_freespace() returns the amount of space that is unused by + * any objects in the file. + * + * The interpretation of this number depends on the configured free space + * management strategy. For example, if the HDF5 library only tracks free + * space in a file from a file open or create until that file is closed, + * then this routine will report the free space that has been created + * during that interval. + * + * \since 1.6.1 + * + */ H5_DLL hssize_t H5Fget_freespace(hid_t file_id); -H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); -H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); -H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); -H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); -H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr); -H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, - size_t *cur_size_ptr, int *cur_num_entries_ptr); -H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); -H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); -H5_DLL herr_t H5Fget_info(hid_t obj_id, H5F_info_t *bh_info); -H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns the size of an HDF5 file (in bytes) + * + * \file_id + * \param[out] size Size of the file, in bytes + * + * \return \herr_t + * + * \details H5Fget_filesize() returns the size of the HDF5 file specified by + * \p file_id. + * + * The returned size is that of the entire file, as opposed to only + * the HDF5 portion of the file. I.e., size includes the user block, + * if any, the HDF5 portion of the file, and any data that may have + * been appended beyond the data written through the HDF5 library. + * + * \since 1.6.3 + * + */ +H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); +/** + * \ingroup H5F + * + * \brief Retrieves a copy of the image of an existing, open file + * + * \file_id + * \param[out] buf_ptr Pointer to the buffer into which the image of the + * HDF5 file is to be copied. If \p buf_ptr is NULL, + * no data will be copied but the function’s return value + * will still indicate the buffer size required (or a + * negative value on error). + * \param[out] buf_len Size of the supplied buffer + * + * \return ssize_t + * + * \details H5Fget_file_image() retrieves a copy of the image of an existing, + * open file. This routine can be used with files opened using the + * SEC2 (or POSIX), STDIO, and Core (or Memory) virtual file drivers + * (VFDs). + * + * If the return value of H5Fget_file_image() is a positive value, it + * will be the length in bytes of the buffer required to store the + * file image. So if the file size is unknown, it can be safely + * determined with an initial H5Fget_file_image() call with buf_ptr + * set to NULL. The file image can then be retrieved with a second + * H5Fget_file_image() call with \p buf_len set to the initial call’s + * return value. + * + * While the current file size can also be retrieved with + * H5Fget_filesize(), that call may produce a larger value than is + * needed. The value returned by H5Fget_filesize() includes the user + * block, if it exists, and any unallocated space at the end of the + * file. It is safe in all situations to get the file size with + * H5Fget_file_image() and it often produces a value that is more + * appropriate for the size of a file image buffer. + * + * \note \Bold{Recommended Reading:} This function is part of the file image + * operations feature set. It is highly recommended to study the guide + * \ref_file_image_ops before using this feature set. + * + * \attention H5Pget_file_image() will fail, returning a negative value, if the + * file is too large for the supplied buffer. + * + * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks() + * + * \since 1.8.0 + * + */ +H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); +/** + * \ingroup MDC + * + * \brief Obtains current metadata cache configuration for target file + * + * \file_id + * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance in which + * the current metadata cache configuration is to be + * reported. The fields of this structure are discussed + * \ref H5AC-cache-config-t "here". + * \return \herr_t + * + * \note The \c in direction applies only to the H5AC_cache_config_t::version + * field. All other fields are out parameters. + * + * \details H5Fget_mdc_config() loads the current metadata cache configuration + * into the instance of H5AC_cache_config_t pointed to by the \p config_ptr + * parameter.\n + * The fields of the H5AC_cache_config_t structure are shown below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \brief Attempts to configure metadata cache of target file + * + * \file_id + * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance + * containing the desired configuration. + * The fields of this structure are discussed + * \ref H5AC-cache-config-t "here". + * \return \herr_t + * + * \details H5Fset_mdc_config() attempts to configure the file's metadata cache + * according configuration supplied in \p config_ptr. + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \brief Obtains target file's metadata cache hit rate + * + * \file_id + * \param[out] hit_rate_ptr Pointer to the double in which the hit rate is returned. Note that + * \p hit_rate_ptr is undefined if the API call fails + * \return \herr_t + * + * \details H5Fget_mdc_hit_rate() queries the metadata cache of the target file to obtain its hit rate + * \Code{(cache hits / (cache hits + cache misses))} since the last time hit rate statistics + * were reset. If the cache has not been accessed since the last time the hit rate stats were + * reset, the hit rate is defined to be 0.0. + * + * The hit rate stats can be reset either manually (via H5Freset_mdc_hit_rate_stats()), or + * automatically. If the cache's adaptive resize code is enabled, the hit rate stats will be + * reset once per epoch. If they are reset manually as well, the cache may behave oddly. + * + * See the overview of the metadata cache in the special topics section of the user manual for + * details on the metadata cache and its adaptive resize algorithms. + * + */ +H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr); +/** + * \ingroup MDC + * + * \brief Obtains current metadata cache size data for specified file + * + * \file_id + * \param[out] max_size_ptr Pointer to the location in which the current cache maximum size is to be + * returned, or NULL if this datum is not desired + * \param[out] min_clean_size_ptr Pointer to the location in which the current cache minimum clean + * size is to be returned, or NULL if that datum is not desired + * \param[out] cur_size_ptr Pointer to the location in which the current cache size is to be returned, + * or NULL if that datum is not desired + * \param[out] cur_num_entries_ptr Pointer to the location in which the current number of entries in + * the cache is to be returned, or NULL if that datum is not desired + * \returns \herr_t + * + * \details H5Fget_mdc_size() queries the metadata cache of the target file for the desired size + * information, and returns this information in the locations indicated by the pointer + * parameters. If any pointer parameter is NULL, the associated data is not returned. + * + * If the API call fails, the values returned via the pointer parameters are undefined. + * + * If adaptive cache resizing is enabled, the cache maximum size and minimum clean size + * may change at the end of each epoch. Current size and current number of entries can + * change on each cache access. + * + * Current size can exceed maximum size under certain conditions. See the overview of the + * metadata cache in the special topics section of the user manual for a discussion of this. + * + */ +H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, + size_t *cur_size_ptr, int *cur_num_entries_ptr); +/** + * \ingroup MDC + * + * \brief Resets hit rate statistics counters for the target file + * + * \file_id + * \returns \herr_t + * + * \details + * \parblock + * H5Freset_mdc_hit_rate_stats() resets the hit rate statistics counters in the metadata cache + * associated with the specified file. + * + * If the adaptive cache resizing code is enabled, the hit rate statistics are reset at the beginning + * of each epoch. This API call allows you to do the same thing from your program. + * + * The adaptive cache resizing code may behave oddly if you use this call when adaptive cache resizing + * is enabled. However, the call should be useful if you choose to control metadata cache size from your + * program. + * + * See \ref_mdc_in_hdf5 for details about the metadata cache and the adaptive cache resizing + * algorithms. If you have not read, understood, and thought about the material covered in that + * documentation, + * you should not be using this API call. + * \endparblock + * + */ +H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \obj_id + * \param[out] name Buffer for the file name + * \param[in] size Size, in bytes, of the \p name buffer + * + * \return Returns the length of the file name if successful; otherwise returns + * a negative value. + * + * \details H5Fget_name() retrieves the name of the file to which the object \p + * obj_id belongs. The object can be a file, group, dataset, + * attribute, or named datatype. + * + * Up to \p size characters of the file name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of + * size, is unknown, a preliminary H5Fget_name() call can be made by + * setting \p name to NULL. The return value of this call will be the + * size of the file name; that value plus one (1) can then be assigned + * to size for a second H5Fget_name() call, which will retrieve the + * actual name. (The value passed in with the parameter \p size must + * be one greater than size in bytes of the actual name in order to + * accommodate the null terminator; if \p size is set to the exact + * size of the name, the last byte passed back will contain the null + * terminator and the last character will be missing from the name + * passed back to the calling application.) + * + * If an error occurs, the buffer pointed to by \p name is unchanged + * and the function returns a negative value. + * + * \since 1.6.3 + * + */ +H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \fgdta_obj_id + * \param[out] file_info Buffer for global file information + * + * \return \herr_t + * + * \details H5Fget_info() returns global information for the file associated + * with the object identifier \p obj_id in the H5F_info_t \c struct + * named \p file_info. + * + * \p obj_id is an identifier for any object in the file of interest. + * + * H5F_info_t struct is defined in H5Fpublic.h as follows: + * \snippet this H5F_info_t_snip + * + * \c super_ext_size is the size of the superblock extension. + * + * The \c sohm sub-struct contains shared object header message + * information as follows: + * \li \c hdr_size is the size of the shared object header message. + * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as + * follows: \snippet H5public.h H5_ih_info_t_snip + * + * \li \p index_size is the summed size of all the shared object + * header indexes. Each index might be either a B-tree or + * a list. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_info(hid_t obj_id, H5F_info_t *file_info); +/** + * \ingroup H5F + * + * \brief Clears the external link open file cache + * + * \file_id + * \return \herr_t + * + * \details H5Fclear_elink_file_cache() evicts all the cached child files in + * the specified file’s external file cache, causing them to be closed + * if there is nothing else holding them open. + * + * H5Fclear_elink_file_cache() does not close the cache itself; + * subsequent external link traversals from the parent file will again + * cache the target file. See H5Pset_elink_file_cache_size() for + * information on closing the file cache. + * + * \see H5Pset_elink_file_cache_size(), H5Pget_elink_file_cache_size() + * + * \since 1.8.7 + * + */ +H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); #ifdef H5_HAVE_PARALLEL +/** + * \ingroup PH5F + * + * \brief Sets the MPI atomicity mode + * + * \file_id + * \param[in] flag Logical flag for atomicity setting. Valid values are: + * \li \c 1 -- Sets MPI file access to atomic mode. + * \li \c 0 -- Sets MPI file access to nonatomic mode. + * \returns \herr_t + * + * \par Motivation + * H5Fset_mpi_atomicity() is applicable only in parallel environments using MPI I/O. + * The function is one of the tools used to ensure sequential consistency. This means + * that a set of operations will behave as though they were performed in a serial + * order consistent with the program order. + * + * \details + * \parblock + * H5Fset_mpi_atomicity() sets MPI consistency semantics for data access to the file, + * \p file_id. + * + * If \p flag is set to \c 1, all file access operations will appear atomic, guaranteeing + * sequential consistency. If \p flag is set to \c 0, enforcement of atomic file access + * will be turned off. + * + * H5Fset_mpi_atomicity() is a collective function and all participating processes must + * pass the same values for \p file_id and \p flag. + * + * This function is available only when the HDF5 library is configured with parallel support + * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver + * (see H5Pset_fapl_mpio()). + * \endparblock + * + * \attention + * \parblock + * H5Fset_mpi_atomicity() calls \Code{MPI_File_set_atomicity} underneath and is not supported + * if the execution platform does not support \Code{MPI_File_set_atomicity}. When it is + * supported and used, the performance of data access operations may drop significantly. + * + * In certain scenarios, even when \Code{MPI_File_set_atomicity} is supported, setting + * atomicity with H5Fset_mpi_atomicity() and \p flag set to 1 does not always yield + * strictly atomic updates. For example, some H5Dwrite() calls translate to multiple + * \Code{MPI_File_write_at} calls. This happens in all cases where the high-level file + * access routine translates to multiple lower level file access routines. + * The following scenarios will raise this issue: + * \li Non-contiguous file access using independent I/O + * \li Partial collective I/O using chunked access + * \li Collective I/O using filters or when data conversion is required + * + * This issue arises because MPI atomicity is a matter of MPI file access operations rather + * than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level. + * To accomplish this, the application must set a barrier after a write, H5Dwrite(), but before + * the next read, H5Dread(), in addition to calling H5Fset_mpi_atomicity().The barrier will + * guarantee that all underlying write operations execute atomically before the read + * operations starts. This ensures additional ordering semantics and will normally produce + * the desired behavior. + * \endparblock + * + * \see \ref_cons_semantics + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); +/** + * \ingroup PH5F + * + * \brief Retrieves the atomicity mode in use + * + * \file_id + * \param[out] flag Logical flag for atomicity setting. Valid values are: + * \li 1 -- MPI file access is set to atomic mode. + * \li 0 -- MPI file access is set to nonatomic mode. + * \returns \herr_t + * + * \details H5Fget_mpi_atomicity() retrieves the current consistency semantics mode for + * data access for the file \p file_id. + * + * Upon successful return, \p flag will be set to \c 1 if file access is set + * to atomic mode and \c 0 if file access is set to nonatomic mode. + * + * \see \ref_cons_semantics + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 745fc85..7f1faf8 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -41,22 +41,31 @@ /* Public Typedefs */ /*******************/ -/* Types of link storage for groups */ +//! <!-- [H5G_storage_t_snip] --> +/** + * Types of link storage for groups + */ typedef enum H5G_storage_type_t { - H5G_STORAGE_TYPE_UNKNOWN = -1, /* Unknown link storage type */ - H5G_STORAGE_TYPE_SYMBOL_TABLE, /* Links in group are stored with a "symbol table" */ - /* (this is sometimes called "old-style" groups) */ - H5G_STORAGE_TYPE_COMPACT, /* Links are stored in object header */ - H5G_STORAGE_TYPE_DENSE /* Links are stored in fractal heap & indexed with v2 B-tree */ + H5G_STORAGE_TYPE_UNKNOWN = -1, /**< Unknown link storage type */ + H5G_STORAGE_TYPE_SYMBOL_TABLE, /**< Links in group are stored with a "symbol table" */ + /**< (this is sometimes called "old-style" groups) */ + H5G_STORAGE_TYPE_COMPACT, /**< Links are stored in object header */ + H5G_STORAGE_TYPE_DENSE /**< Links are stored in fractal heap & indexed with v2 B-tree */ } H5G_storage_type_t; +//! <!-- [H5G_storage_t_snip] --> -/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */ +//! <!-- [H5G_info_t_snip] --> +/** + * Information struct for group for + * H5Gget_info(), H5Gget_info_by_name(), and H5Gget_info_by_idx() + */ typedef struct H5G_info_t { - H5G_storage_type_t storage_type; /* Type of storage for links in group */ - hsize_t nlinks; /* Number of links in group */ - int64_t max_corder; /* Current max. creation order value for group */ - hbool_t mounted; /* Whether group has a file mounted on it */ + H5G_storage_type_t storage_type; /**< Type of storage for links in group */ + hsize_t nlinks; /**< Number of links in group */ + int64_t max_corder; /**< Current max. creation order value for group */ + hbool_t mounted; /**< Whether group has a file mounted on it */ } H5G_info_t; +//! <!-- [H5G_info_t_snip] --> /********************/ /* Public Variables */ @@ -69,14 +78,342 @@ typedef struct H5G_info_t { extern "C" { #endif -H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id); -H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id); -H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); -H5_DLL hid_t H5Gget_create_plist(hid_t group_id); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a new group and links it into the file + * + * \fgdta_loc_id + * \param[in] name Name of the group to create + * \lcpl_id + * \gcpl_id + * \gapl_id + * + * \return \hid_t{group} + * + * \details H5Gcreate2() creates a new group in a file. After a + * group has been created, links to datasets and to other groups + * can be added. + * + * The \p loc_id and \p name parameters specify where the group + * is located. \p loc_id may be a file, group, dataset, named + * datatype or attribute in the file. If an attribute, dataset, + * or named datatype is specified for \p loc_id then the group + * will be created at the location where the attribute, dataset, + * or named datatype is attached. \p name is the link to the group; + * \p name may be either an absolute path in the file (the links + * from the root group to the new group) or a relative path from + * \p loc_id (the link(s) from the group specified by \p loc_id + * to the new group). + * + * \p lcpl_id, \p gcpl_id, and \p gapl_id are property list + * identifiers. These property lists govern how the link to the + * group is created, how the group is created, and how the group + * can be accessed in the future, respectively. #H5P_DEFAULT can + * be passed in if the default properties are appropriate for + * these property lists. Currently, there are no APIs for the + * group access property list; use #H5P_DEFAULT. + * + * The group identifier should be closed by H5Gclose() when access + * is no longer required to prevent resource leaks. + * + * \since 1.8.0 + * + * \see H5Gopen2(), H5Gclose() + * + */ +H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a new empty group without linking it into the file structure + * + * \fgdta_loc_id + * \gcpl_id + * \gapl_id + * + * \return \hid_t{group} + * + * \details H5Gcreate_anon() creates a new empty group in the file + * specified by \p loc_id. With default settings, H5Gcreate_anon() + * provides similar functionality to that provided by + * H5Gcreate1(), with the differences described in the list below. + * + * The new group’s creation and access properties are specified + * in \p gcpl_id and \p gapl_id, respectively. + * + * H5Gcreate_anon() returns a new group identifier. This identifier + * must be linked into the HDF5 file structure with H5Olink() + * or it will be deleted from the file when the file is closed. + * + * The differences between this function and H5Gcreate1() are + * as follows: + * + * \li H5Gcreate1() does not provide for the use of custom property + * lists; H5Gcreate1() always uses default properties. + * \li H5Gcreate_anon() neither provides the new group’s name + * nor links it into the HDF5 file structure; those actions + * must be performed separately through a call to H5Olink(), + * which offers greater control over linking. + * \li H5Gcreate_anon() does not directly provide a hint mechanism + * for the group’s heap size. Comparable information can be + * included in the group creation property list \p gcpl_id through + * a H5Pset_local_heap_size_hint() call. + * + * A group created with this function should be closed with + * H5Gclose() when the group is no longer needed so that resource + * leaks will not develop. + * + * \see H5Olink(), H5Dcreate(), Using Identifiers + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Opens an existing group in a file + * + * \fgdta_loc_id + * \param[in] name Name of the group to open + * \gapl_id + * + * \return \hid_t{group} + * + * \details H5Gopen2() opens an existing group, \p name, at the location + * specified by \p loc_id. + * + * With default settings, H5Gopen2() provides similar functionality + * to that provided by H5Gopen(). The only difference is that + * H5Gopen2() can provide a group access property list, \p gapl_id. + * + * H5Gopen2() returns a group identifier for the group that was + * opened. This group identifier should be released by H5Gclose() + * when it is no longer needed to prevent resource leaks. + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ +H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Gets a group creation property list identifier + * + * \group_id + * + * \return \hid_t{creation property list} + * + * \details H5Gget_create_plist() returns an identifier for the group creation + * property list associated with the group specified by \p group_id. + * + * The creation property list identifier should be released with + * H5Gclose() to prevent resource leaks. + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ +H5_DLL hid_t H5Gget_create_plist(hid_t group_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Retrieves information about a group + * + * \fgdta_loc_id + * \param[out] ginfo Struct in which group information is returned + * + * \return \hid_t{group} + * + * \details H5Gget_info() retrieves information about the group at location + * specified by \p loc_id. The information is returned in the \p ginfo. + * + * \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h) + * as follows: + * + * \snippet this H5G_info_t_snip + * Possible values of \p storage_type are: + * \storage_type + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Retrieves information about a group by its name + * + * \fgdta_loc_id + * \param[in] name Name of the group to query + * \param[out] ginfo Struct in which group information is returned + * \lapl_id + * + * \return \herr_t + * + * \details H5Gget_info_by_name() retrieves information about the group \p name + * at location specified by \p loc_id. The information is returned in + * the \p ginfo struct. + * + * If \p loc_id specifies the group for which information is queried, + * then the group's \p name can be a dot (.). + * + * \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h) + * as follows: + * + * \snippet this H5G_info_t_snip + * Possible values of \p storage_type are: + * \storage_type + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Retrieves information about a group, according to the group’s + * position within an index + * + * \fgdta_loc_id + * \param[in] group_name Name of the group to query + * \param[in] idx_type Transient index identifying object + * \param[in] order Transient index identifying object + * \param[in] n Position in the index of the group to query + * \param[out] ginfo Struct in which group information is returned + * \lapl_id + * + * \return Returns + * \li The size of the object name if successful, or + * \li 0 if no name is associated with the group identifier, or + * \li negative value, if failure occurred + * + * \details H5Gget_info_by_idx() retrieves the same information + * about a group as retrieved by the function H5Gget_info(), + * but the means of identifying the group differs; the group is + * identified by position in an index rather than by name. + * + * \p loc_id and \p group_name specify the group containing + * the group for which information is sought. The groups in \p + * group_name are indexed by \p idx_type; the group for which + * information is retrieved is identified in that index by index + * order, \p order, and index position, \p n. + * + * If \p loc_id specifies the group containing the group for + * which information is queried, \p group_name can be a dot (.). + * + * Valid values for \p index_type are as follows: + * \indexes + * The order in which the index is to be examined, as specified + * by \p order, can be one of the following: + * \orders + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Flushes all buffers associated with a group to disk + * + * \group_id + * + * \return \herr_t + * + * \details H5Gflush() causes all buffers associated with a group to be + * immediately flushed to disk without removing the data from + * the cache. + * + * \attention + * HDF5 does not possess full control over buffering. H5G_FLUSH + * flushes the internal HDF5 buffers and then asks the operating + * system (the OS) to flush the system buffers for the open + * files. After that, the OS is responsible for ensuring that + * the data is actually flushed to disk. + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ +H5_DLL herr_t H5Gflush(hid_t group_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Refreshes all buffers associated with a group + * + * \group_id + * + * \return \herr_t + * + * \details H5Grefresh() causes all buffers associated with a group to be + * cleared and immediately re-loaded with updated contents from disk. + * + * This function essentially closes the group, evicts all + * metadata associated with it from the cache, and then re-opens + * the group. The reopened group is automatically re-registered + * with the same identifier. + * + * \since 1.8.0 + * + * \see H5Gcreate2(), H5Gclose() + * + */ +H5_DLL herr_t H5Grefresh(hid_t group_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Closes the specified group + * + * \group_id + * + * \return \herr_t + * + * \details H5Gclose() releases resources used by a group which was + * opened by H5Gcreate() or H5Gopen(). After closing a group, + * \p group_id cannot be used again until another H5Gcreate() + * or H5Gopen() is called on it. + * + * Failure to release a group with this call will result in + * resource leaks. + * + * \par Example + * \snippet H5F_examples.c mount + * + * \since 1.0.0 + * + */ H5_DLL herr_t H5Gclose(hid_t group_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -102,56 +439,647 @@ H5_DLL herr_t H5Gclose(hid_t group_id); /* Typedefs */ -/* +//! <!-- [H5G_obj_t_snip] --> +/** * An object has a certain type. The first few numbers are reserved for use * internally by HDF5. Users may add their own types with higher values. The - * values are never stored in the file -- they only exist while an - * application is running. An object may satisfy the `isa' function for more - * than one type. + * values are never stored in the file -- they only exist while an application + * is running. An object may satisfy the `isa' function for more than one type. + * + * \deprecated */ typedef enum H5G_obj_t { - H5G_UNKNOWN = -1, /* Unknown object type */ - H5G_GROUP, /* Object is a group */ - H5G_DATASET, /* Object is a dataset */ - H5G_TYPE, /* Object is a named data type */ - H5G_LINK, /* Object is a symbolic link */ - H5G_UDLINK, /* Object is a user-defined link */ - H5G_RESERVED_5, /* Reserved for future use */ - H5G_RESERVED_6, /* Reserved for future use */ - H5G_RESERVED_7 /* Reserved for future use */ + H5G_UNKNOWN = -1, /**< Unknown object type */ + H5G_GROUP, /**< Object is a group */ + H5G_DATASET, /**< Object is a dataset */ + H5G_TYPE, /**< Object is a named data type */ + H5G_LINK, /**< Object is a symbolic link */ + H5G_UDLINK, /**< Object is a user-defined link */ + H5G_RESERVED_5, /**< Reserved for future use */ + H5G_RESERVED_6, /**< Reserved for future use */ + H5G_RESERVED_7 /**< Reserved for future use */ } H5G_obj_t; +//! <!-- [H5G_obj_t_snip] --> -/* Prototype for H5Giterate() operator */ +//! <!-- [H5G_iterate_t_snip] --> +/** + * Callback for H5Giterate() + * + * \deprecated + */ typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data); +//! <!-- [H5G_iterate_t_snip] --> -/* Information about an object */ +//! <!-- [H5G_stat_t_snip] --> +/** + * Information about an object + * + * \deprecated + */ typedef struct H5G_stat_t { - unsigned long fileno[2]; /*file number */ - unsigned long objno[2]; /*object number */ - unsigned nlink; /*number of hard links to object*/ - H5G_obj_t type; /*basic object type */ - time_t mtime; /*modification time */ - size_t linklen; /*symbolic link value length */ - H5O_stat_t ohdr; /* Object header information */ + unsigned long fileno[2]; /**< file number */ + unsigned long objno[2]; /**< object number */ + unsigned nlink; /**< number of hard links to object*/ + H5G_obj_t type; /**< basic object type */ + time_t mtime; /**< modification time */ + size_t linklen; /**< symbolic link value length */ + H5O_stat_t ohdr; /**< Object header information */ } H5G_stat_t; +//! <!-- [H5G_stat_t_snip] --> /* Function prototypes */ -H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint); -H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name); -H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name); -H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id, - const char *new_name); -H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name); -H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name); -H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name); -H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/); -H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment); -H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf); -H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data); -H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs); -H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link, - H5G_stat_t *statbuf /*out*/); -H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a new group and links it into the file + * + * \fgdta_loc_id + * \param[in] name Name of the group to create + * \param[in] size_hint The number of bytes to reserve for the names + * that will appear in the group + * + * \return \hid_t{group} + * + * \deprecated This function is deprecated in favor of H5Gcreate2(). + * + * \details H5Gcreate1() creates a new group with the specified name at the + * specified location, \p loc_id. \p loc_id may be a file, group, + * dataset, named datatype or attribute. If an attribute, dataset, or + * named datatype is specified for \p loc_id then the group will be + * created at the location where the attribute, dataset, or named + * datatype is attached. The name, name, must not already be taken by + * some other object and all parent groups must already exist. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires that + * any intermediate groups specified in the path already exist. + * + * The length of a group name, or of the name of any object within a + * group, is not limited. + * + * \p size_hint is a hint for the number of bytes to reserve to store + * the names which will be eventually added to the new group. This + * value must be between 0 and UINT32_MAX (inclusive). If this + * parameter is zero, a default value will be used. + * + * The return value is a group identifier for the open group. This + * group identifier should be closed by calling H5Gclose() when it is + * no longer needed. + * + * See H5Gcreate_anon() for a discussion of the differences between + * H5Gcreate1() and H5Gcreate_anon(). + * + * \par Example + * \snippet H5F_examples.c mount + * + * \version 1.8.0 Function H5Gcreate() renamed to H5Gcreate1() and deprecated + * in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Opens an existing group for modification and returns a group + * identifier for that group + * + * \fgdta_loc_id + * \param[in] name Name of the group to open + * + * \return \hid_t{group} + * + * \deprecated This function is deprecated in favor of H5Gopen2(). + * + * \details H5Gopen1() opens an existing group, \p name, at the location + * specified by \p loc_id. + * + * H5Gopen1() returns a group identifier for the group that was + * opened. This group identifier should be released by calling + * H5Gclose() when it is no longer needed. + * + * \version 1.8.0 The function H5Gopen() was renamed to H5Gopen1() + * and deprecated in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a link of the specified type from \p new_name to \p + * cur_name + * + * \fg_loc_id{cur_loc_id} + * \param[in] type Link type + * \param[in] cur_name Name of the existing object + * \param[in] new_name New name for the object + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Glink() creates a new name for an object that has some current + * name, possibly one of many names it currently has. + * + * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify + * the name of an existing object and both names are interpreted + * relative to \p cur_loc_id, which is either a file identifier or a + * group identifier. + * + * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything + * and is interpreted at lookup time relative to the group which + * contains the final component of \p new_name. For instance, if \p + * cur_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a + * request is made for \Code{./x/y/bar}, then the actual object looked + * up is \Code{./x/y/./foo}. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a link of the specified type from \p cur_name to \p + * new_name + * + * \fg_loc_id{cur_loc_id} + * \param[in] cur_name Name of the existing object + * \param[in] type Link type + * \fg_loc_id{new_loc_id} + * \param[in] new_name New name for the object + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Glink2() creates a new name for an object that has some current + * name, possibly one of many names it currently has. + * + * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify the + * name of an existing object and both names are interpreted relative + * to \p cur_loc_id and \p new_loc_id, respectively, which are either + * file identifiers or group identifiers. + * + * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything + * and is interpreted at lookup time relative to the group which + * contains the final component of \p new_name. For instance, if \p + * current_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a + * request is made for \Code{./x/y/bar}, then the actual object looked + * up is \Code{./x/y/./foo}. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id, + const char *new_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Renames an object within an HDF5 file + * + * \fg_loc_id{src_loc_id} + * \param[in] src_name Object's original name + * \param[in] dst_name Object's new name + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Gmove() renames an object within an HDF5 file. The original name, + * \p src_name, is unlinked from the group graph and the new name, \p + * dst_name, is inserted as an atomic operation. Both names are + * interpreted relative to \p loc_id, which is either a file or a group + * identifier. + * + * \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. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Renames an object within an HDF5 file + * + * \fg_loc_id{src_loc_id} + * \param[in] src_name Object's original name + * \fg_loc_id{dst_loc_id} + * \param[in] dst_name Object's new name + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Gmove2() renames an object within an HDF5 file. The original name, + * \p src_name, is unlinked from the group graph and the new name, \p + * dst_name, is inserted as an atomic operation. + * + * \p src_name and \p dst_name are interpreted relative to \p + * src_loc_id and \p dst_loc_id, respectively, which are either file or + * group identifiers. + * + * \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. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Removes the link to an object from a group + * + * \fg_loc_id{loc_id} + * \param[in] name Name of the object to unlink + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Ldelete(). + * + * \details H5Gunlink() removes the object specified by \p name from the group + * graph and decrements the link count for the object to which \p name + * points. This action eliminates any association between name and the + * object to which name pointed. + * + * Object headers keep track of how many hard links refer to an object; + * when the link count reaches zero, the object can be removed from the + * file. Objects which are open are not removed until all identifiers + * to the object are closed. + * + * If the link count reaches zero, all file space associated with the + * object will be released, i.e., identified in memory as freespace. If + * any object identifier is open for the object, the space will not be + * released until after the object identifier is closed. + * + * 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. + * + * \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. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns the name of the object that the symbolic link points to + * + * \fg_loc_id{loc_id} + * \param[in] name Symbolic link to the object whose name is to be returned + * \param[in] size Maximum number of characters of value to be returned + * \param[out] buf A buffer to hold the name of the object being sought + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Lget_val(). + * + * \details H5Gget_linkval() returns up to size characters of the name of the + * object that the symbolic link name points to. + * + * The parameter \p loc_id is a file or group identifier. + * + * The parameter \p name must be a symbolic link pointing to the + * desired object and must be defined relative to \p loc_id. + * + * If size is smaller than the size of the returned object name, then + * the name stored in the buffer value will not be \c NULL terminated. + * + * This function fails if \p name is not a symbolic link. The presence + * of a symbolic link can be tested by passing zero for \p size and \p + * NULL for value. + * + * This function should be used only after H5Lget_info1() (or the + * deprecated function H5Gget_objinfo()) has been called to verify that + * name is a symbolic link. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Sets comment for specified object + * + * \fgdt_loc_id + * \param[in] name Name of the object whose comment is to be set or reset + * name must be \Code{'.'} (dot) if \p loc_id fully specifies + * the object for which the comment is to be set. + * \param[in] comment The new comment + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Oset_comment(). + * + * \details H5Gset_comment() sets the comment for the object specified by \p + * loc_id and name to comment. Any previously existing comment is + * overwritten. + * + * \p loc_id can specify any object in the file. name can be one of the + * following: + * \li The name of the object relative to \p loc_id + * \li An absolute name of the object, starting from \c /, the file’s + * root group + * \li A dot (\c .), if \p loc_id fully specifies the object + * + * If \p comment is the empty string or a null pointer, the comment + * message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object header, + * e.g., datasets, groups, and named datatypes, but not symbolic links. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Retrieves comment for specified object + * + * \fgdt_loc_id + * \param[in] name Name of the object whose comment is to be set or reset + * name must be \Code{'.'} (dot) if \p loc_id fully specifies + * the object for which the comment is to be set. + * \param[in] bufsize Maximum number of comment characters to be returned in \p buf. + * \param[in] buf The comment + * + * \return Returns the number of characters in the comment, counting the \c NULL + * terminator, if successful; the value returned may be larger than + * \p bufsize. Otherwise returns a negative value. + * + * \deprecated This function is deprecated in favor of the function + * H5Oget_comment(). + * + * \details H5Gget_comment() retrieves the comment for the the object specified + * by \p loc_id and \p name. The comment is returned in the buffer \p + * buf. + * + * \p loc_id can specify any object in the file. name can be one of the + * following: + * \li The name of the object relative to \p loc_id + * \li An absolute name of the object, starting from \c /, the file’s + * root group + * \li A dot (\c .), if \p loc_id fully specifies the object + * + * At most bufsize characters, including a null-terminator, are + * returned in \p buf. The returned value is not null-terminated if the + * comment is longer than the supplied buffer. If the size of the + * comment is unknown, a preliminary \p H5Gget_comment() call will + * return the size of the comment, including space for the + * null-terminator. + * + * If an object does not have a comment, the empty string is returned + * in comment. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Iterates over the entries of a group invoking a callback for each + * entry encountered + * + * \fg_loc_id + * \param[in] name Group over which the iteration is performed + * \param[in,out] idx Location at which to begin the iteration + * \param[in] op Operation to be performed on an object at each step of the + * iteration + * \param[in,out] op_data Data associated with the operation + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Literate1(). + * + * \details H5Giterate() iterates over the members of name in the file or group + * specified with \p loc_id. For each object in the group, the \p + * op_data and some additional information, specified below, are passed + * to the operator function. The iteration begins with the \p idx + * object in the group and the next element to be processed by the + * operator is returned in \p idx. If \p idx is NULL, then the iterator + * starts at the first group member; since no stopping point is + * returned in this case, the iterator cannot be restarted if one of + * the calls to its operator returns non-zero. H5Giterate() does not + * recursively follow links into subgroups of the specified group. + * + * The prototype for \ref H5G_iterate_t is: + * \snippet this H5G_iterate_t_snip + * + * The operation receives the group identifier for the group being + * iterated over, \p group, the name of the current object within + * the group, \p name, and the pointer to the operator data + * passed in to H5Giterate(), \p op_data. + * + * The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when all + * group members have been processed. + * \li Positive causes the iterator to immediately return that positive + * value, indicating short-circuit success. The iterator can be + * restarted at the next group member. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * group member. + * + * H5Giterate() assumes that the membership of the group identified by + * \p name remains unchanged through the iteration. If the membership + * changes during the iteration, the function's behavior is undefined. + * + * H5Giterate() is not recursive. In particular, if a member of \p name + * is found to be a group, call it \c subgroup_a, H5Giterate() does not + * examine the members of \c subgroup_a. When recursive iteration is + * required, the application must handle the recursion, explicitly + * calling H5Giterate() on discovered subgroups. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns number of objects in the group specified by its identifier + * + * \fg_loc_id + * \param[out] num_objs Number of objects in the group + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Gget_info(). + * + * \details H5Gget_num_objs() returns number of objects in a group. Group is + * specified by its identifier \p loc_id. If a file identifier is + * passed in, then the number of objects in the root group is returned. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns information about an object. + * + * \fgdt_loc_id + * \param[in] name Name of the object for which status is being sought + * \param[in] follow_link Link flag + * \param[out] statbuf Buffer in which to return information about the object + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the functions H5Oget_info() + * and H5Lget_info1(). + * + * \details H5Gget_objinfo() returns information about the specified object + * through the \p statbuf argument. + * + * A file or group identifier, \p loc_id, and an object name, \p name, + * relative to \p loc_id, are commonly used to specify the + * object. However, if the object identifier is already known to the + * application, an alternative approach is to use that identifier, \c + * obj_id, in place of \p loc_id, and a dot (\c .) in place of \p + * name. Thus, the alternative versions of the first portion of an + * H5Gget_objinfo() call would be as follows: + * \code + * H5Gget_objinfo (loc_id name ...) + * H5Gget_objinfo (obj_id . ...) + * \endcode + * + * If the object is a symbolic link and follow_link is zero (0), then + * the information returned describes the link itself; otherwise the + * link is followed and the information returned describes the object + * to which the link points. If \p follow_link is non-zero but the + * final symbolic link is dangling (does not point to anything), then + * an error is returned. The \p statbuf fields are undefined for an + * error. The existence of an object can be tested by calling this + * function with a \c NULL \p statbuf. + * + * H5Gget_objinfo() fills in the following data structure (defined in + * H5Gpublic.h): + * \snippet this H5G_stat_t_snip + * + * where \ref H5O_stat_t (defined in H5Opublic.h) is: + * \snippet H5Opublic.h H5O_stat_t_snip + * + * \attention Some systems will be able to record the time accurately but unable + * to retrieve the correct time; such systems (e.g., Irix64) will + * report an \c mtime value of 0 (zero). + * + * \version 1.8.0 Function deprecated in this release. + * \version 1.6.1 Two new fields were added to the \ref H5G_stat_t struct in + * this release. + * + */ +H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link, + H5G_stat_t *statbuf /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns a name of an object specified by an index + * + * \fg_loc_id + * \param[in] idx Transient index identifying object + * \param[in,out] name Pointer to user-provided buffer the object name + * \param[in] size Name length + * + * \return Returns the size of the object name if successful, or 0 if no name is + * associated with the group identifier. Otherwise returns a negative + * value. + * + * \deprecated This function is deprecated in favor of the function H5Lget_name_by_idx(). + * + * \details H5Gget_objname_by_idx() returns a name of the object specified by + * the index \p idx in the group \p loc_id. + * + * The group is specified by a group identifier \p loc_id. If + * preferred, a file identifier may be passed in \p loc_id; that file's + * root group will be assumed. + * + * \p idx is the transient index used to iterate through the objects in + * the group. The value of \p idx is any nonnegative number less than + * the total number of objects in the group, which is returned by the + * function H5Gget_num_objs(). Note that this is a transient index; an + * object may have a different index each time a group is opened. + * + * The object name is returned in the user-specified buffer \p name. + * + * If the size of the provided buffer \p name is less or equal the + * actual object name length, the object name is truncated to + * \Code{max_size - 1} characters. + * + * Note that if the size of the object's name is unkown, a preliminary + * call to H5Gget_objname_by_idx() with \p name set to \c NULL will + * return the length of the object's name. A second call to + * H5Gget_objname_by_idx() can then be used to retrieve the actual + * name. + * + * \version 1.8.0 Function deprecated in this release. + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns the type of an object specified by an index + * + * \fg_loc_id + * \param[in] idx Transient index identifying object + * + * \return Returns the type of the object if successful. Otherwise returns a + * negative value. + * + * \deprecated This function is deprecated in favor of the function H5Oget_info(). + * + * \details H5Gget_objtype_by_idx() returns the type of the object specified by + * the index \p idx in the group \p loc_id. + * + * The group is specified by a group identifier \p loc_id. If + * preferred, a file identifier may be passed in \p loc_id; that file's + * root group will be assumed. + * + * \p idx is the transient index used to iterate through the objects in + * the group. This parameter is described in more detail in the + * discussion of H5Gget_objname_by_idx(). + * + * \version 1.8.0 Function deprecated in this release. + * \version 1.6.0 The function return type changed from \c int to the enumerated + * type \ref H5G_obj_t. + * \since 1.6.0 + * + */ H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 1a851c0..7e1ce75 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -21,44 +21,52 @@ /* Public headers needed by this file */ #include "H5public.h" -/* - * Library type values. Start with `1' instead of `0' because it makes the - * tracing output look better when hid_t values are large numbers. Change the - * TYPE_BITS in H5I.c if the MAXID gets larger than 32 (an assertion will - * fail otherwise). +/** + * Library type values. + * \internal Library type values. Start with `1' instead of `0' because it + * makes the tracing output look better when hid_t values are large + * numbers. Change the TYPE_BITS in H5I.c if the MAXID gets larger + * than 32 (an assertion will fail otherwise). * - * When adding types here, add a section to the 'misc19' test in test/tmisc.c - * to verify that the H5I{inc|dec|get}_ref() routines work correctly with it. + * When adding types here, add a section to the 'misc19' test in + * test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines + * work correctly with it. * */ +//! <!-- [H5I_type_t_snip] --> typedef enum H5I_type_t { - H5I_UNINIT = (-2), /* uninitialized type */ - H5I_BADID = (-1), /* invalid Type */ - H5I_FILE = 1, /* type ID for File objects */ - H5I_GROUP, /* type ID for Group objects */ - H5I_DATATYPE, /* type ID for Datatype objects */ - H5I_DATASPACE, /* type ID for Dataspace objects */ - H5I_DATASET, /* type ID for Dataset objects */ - H5I_ATTR, /* type ID for Attribute objects */ - H5I_REFERENCE, /* type ID for Reference objects */ - H5I_VFL, /* type ID for virtual file layer */ - H5I_GENPROP_CLS, /* type ID for generic property list classes */ - H5I_GENPROP_LST, /* type ID for generic property lists */ - H5I_ERROR_CLASS, /* type ID for error classes */ - H5I_ERROR_MSG, /* type ID for error messages */ - H5I_ERROR_STACK, /* type ID for error stacks */ - H5I_NTYPES /* number of library types, MUST BE LAST! */ + H5I_UNINIT = (-2), /**< uninitialized type */ + H5I_BADID = (-1), /**< invalid Type */ + H5I_FILE = 1, /**< type ID for File objects */ + H5I_GROUP, /**< type ID for Group objects */ + H5I_DATATYPE, /**< type ID for Datatype objects */ + H5I_DATASPACE, /**< type ID for Dataspace objects */ + H5I_DATASET, /**< type ID for Dataset objects */ + H5I_ATTR, /**< type ID for Attribute objects */ + H5I_REFERENCE, /**< type ID for Reference objects */ + H5I_VFL, /**< type ID for virtual file layer */ + H5I_GENPROP_CLS, /**< type ID for generic property list classes */ + H5I_GENPROP_LST, /**< type ID for generic property lists */ + H5I_ERROR_CLASS, /**< type ID for error classes */ + H5I_ERROR_MSG, /**< type ID for error messages */ + H5I_ERROR_STACK, /**< type ID for error stacks */ + H5I_NTYPES /**< number of library types, MUST BE LAST! */ } H5I_type_t; +//! <!-- [H5I_type_t_snip] --> -/* Type of atoms to return to users */ +/** + * Type of atoms to return to users + */ typedef int hid_t; #define H5_SIZEOF_HID_T H5_SIZEOF_INT -/* An invalid object ID. This is also negative for error return. */ +/** + * An invalid object ID. This is also negative for error return. + */ #define H5I_INVALID_HID (-1) -/* - * Function for freeing objects. This function will be called with an object +/** + * A function for freeing objects. This function will be called with an object * ID type number and a pointer to the object. The function should free the * object and return non-negative to indicate that the object * can be removed from the ID type. If the function returns negative @@ -66,8 +74,12 @@ typedef int hid_t; */ typedef herr_t (*H5I_free_t)(void *); -/* Type of the function to compare objects & keys */ +/** + * The type of a function to compare objects & keys + */ +//! <!-- [H5I_search_func_t_snip] --> typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key); +//! <!-- [H5I_search_func_t_snip] --> #ifdef __cplusplus extern "C" { @@ -75,25 +87,533 @@ extern "C" { /* Public API functions */ -H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); -H5_DLL void * H5Iobject_verify(hid_t id, H5I_type_t id_type); -H5_DLL void * H5Iremove_verify(hid_t id, H5I_type_t id_type); +/** + * \ingroup H5I + * + * \brief Registers an object under a type and returns an ID for it + * + * \param[in] type The identifier of the type of the new ID + * \param[in] object Pointer to object for which a new ID is created + * + * \return \hid_t{object} + * + * \details H5Iregister() creates and returns a new ID for an object. + * + * \details The \p type parameter is the identifier for the ID type to which + * this new ID will belong. This identifier must have been created by + * a call to H5Iregister_type(). + * + * \details The \p object parameter is a pointer to the memory which the new ID + * will be a reference to. This pointer will be stored by the library + * and returned via a call to H5Iobject_verify(). + * + */ +H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); +/** + * \ingroup H5I + * + * \brief Returns the object referenced by an ID + * + * \param[in] id ID to be dereferenced + * \param[in] type The identifier type + + * + * \return Pointer to the object referenced by \p id on success, NULL on failure. + * + * \details H5Iobject_verify() returns a pointer to the memory referenced by id + * after verifying that \p id is of type \p type. This function is + * analogous to dereferencing a pointer in C with type checking. + * + * \note H5Iobject_verify() does not change the ID it is called on in any way + * (as opposed to H5Iremove_verify(), which removes the ID from its + * type’s hash table). + * + * \see H5Iregister() + * + */ +H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Removes an ID from its type + * + * \param[in] id The ID to be removed from its type + * \param[in] type The identifier type + + * + * \return Returns a pointer to the memory referred to by \p id on success, + * NULL on failure. + * + * \details H5Iremove_verify() first ensures that \p id belongs to \p type. + * If so, it removes \p id from its type and returns the pointer + * to the memory it referred to. This pointer is the same pointer that + * was placed in storage by H5Iregister(). If id does not belong to + * \p type, then NULL is returned. + * + * The \p id parameter is the ID which is to be removed from its type. + * + * The \p type parameter is the identifier for the ID type which \p id + * is supposed to belong to. This identifier must have been created by + * a call to H5Iregister_type(). + * + * \note This function does NOT deallocate the memory that \p id refers to. + * The pointer returned by H5Iregister() must be deallocated by the user + * to avoid memory leaks. + * + */ +H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Retrieves the type of an object + * + * \obj_id{id} + * + * \return Returns the object type if successful; otherwise #H5I_BADID. + * + * \details H5Iget_type() retrieves the type of the object identified by + * \p id. + * + * Valid types returned by the function are: + * \id_types + * + * If no valid type can be determined or the identifier submitted is + * invalid, the function returns #H5I_BADID. + * + * This function is of particular use in determining the type of + * object closing function (H5Dclose(), H5Gclose(), etc.) to call + * after a call to H5Rdereference(). + * + * \note Note that this function returns only the type of object that \p id + * would identify if it were valid; it does not determine whether \p id + * is valid identifier. Validity can be determined with a call to + * H5Iis_valid(). + * + */ H5_DLL H5I_type_t H5Iget_type(hid_t id); -H5_DLL hid_t H5Iget_file_id(hid_t id); -H5_DLL ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size); -H5_DLL int H5Iinc_ref(hid_t id); -H5_DLL int H5Idec_ref(hid_t id); -H5_DLL int H5Iget_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves an identifier for the file containing the specified object + * + * \obj_id{id} + * + * \return \hid_t{file} + * + * \details H5Iget_file_id() returns the identifier of the file associated with + * the object referenced by \p id. + * + * \note Note that the HDF5 library permits an application to close a file + * while objects within the file remain open. If the file containing the + * object \p id is still open, H5Iget_file_id() will retrieve the + * existing file identifier. If there is no existing file identifier for + * the file, i.e., the file has been closed, H5Iget_file_id() will reopen + * the file and return a new file identifier. In either case, the file + * identifier must eventually be released using H5Fclose(). + * + * \since 1.6.3 + * + */ +H5_DLL hid_t H5Iget_file_id(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves a name of an object based on the object identifier + * + * \obj_id{id} + * \param[out] name A buffer for thename associated with the identifier + * \param[in] size The size of the \p name buffer; usually the size of + * the name in bytes plus 1 for a NULL terminator + * + * \return ssize_t + * + * \details H5Iget_name() retrieves a name for the object identified by \p id. + * + * \details Up to size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of + * \p size, is unknown, a preliminary H5Iget_name() call can be made. + * The return value of this call will be the size in bytes of the + * object name. That value, plus 1 for a NULL terminator, is then + * assigned to size for a second H5Iget_name() call, which will + * retrieve the actual name. + * + * If the object identified by \p id is an attribute, as determined + * via H5Iget_type(), H5Iget_name() retrieves the name of the object + * to which that attribute is attached. To retrieve the name of the + * attribute itself, use H5Aget_name(). + * + * If there is no name associated with the object identifier or if the + * name is NULL, H5Iget_name() returns 0 (zero). + * + * \note Note that an object in an HDF5 file may have multiple paths if there + * are multiple links pointing to it. This function may return any one of + * these paths. When possible, H5Iget_name() returns the path with which + * the object was opened. + * + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size); +/** + * \ingroup H5I + * + * \brief Increments the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative reference count of the object ID after + * incrementing it if successful; otherwise a negative value is + * returned. + * + * \details H5Iinc_ref() increments the reference count of the object + * identified by \p id. + * + * The reference count for an object ID is attached to the information + * about an object in memory and has no relation to the number of + * links to an object on disk. + * + * The reference count for a newly created object will be 1. Reference + * counts for objects may be explicitly modified with this function or + * with H5Idec_ref(). When an object ID's reference count reaches + * zero, the object will be closed. Calling an object ID's \c close + * function decrements the reference count for the ID which normally + * closes the object, but if the reference count for the ID has been + * incremented with this function, the object will only be closed when + * the reference count reaches zero with further calls to H5Idec_ref() + * or the object ID's \c close function. + * + * If the object ID was created by a collective parallel call (such as + * H5Dcreate(), H5Gopen(), etc.), the reference count should be + * modified by all the processes which have copies of the ID. + * Generally this means that group, dataset, attribute, file and named + * datatype IDs should be modified by all the processes and that all + * other types of IDs are safe to modify by individual processes. + * + * This function is of particular value when an application is + * maintaining multiple copies of an object ID. The object ID can be + * incremented when a copy is made. Each copy of the ID can then be + * safely closed or decremented and the HDF5 object will be closed + * when the reference count for that that object drops to zero. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Iinc_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Decrements the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative reference count of the object ID after + * decrementing it, if successful; otherwise a negative value is + * returned. + * + * \details H5Idec_ref() decrements the reference count of the object + * identified by \p id. + * + * The reference count for an object ID is attached to the information + * about an object in memory and has no relation to the number of + * links to an object on disk. + * + * The reference count for a newly created object will be 1. Reference + * counts for objects may be explicitly modified with this function or + * with H5Iinc_ref(). When an object identifier’s reference count + * reaches zero, the object will be closed. Calling an object + * identifier’s \c close function decrements the reference count for + * the identifier which normally closes the object, but if the + * reference count for the identifier has been incremented with + * H5Iinc_ref(), the object will only be closed when the reference + * count reaches zero with further calls to this function or the + * object identifier’s \c close function. + * + * If the object ID was created by a collective parallel call (such as + * H5Dcreate(), H5Gopen(), etc.), the reference count should be + * modified by all the processes which have copies of the ID. + * Generally this means that group, dataset, attribute, file and named + * datatype IDs should be modified by all the processes and that all + * other types of IDs are safe to modify by individual processes. + * + * This function is of particular value when an application is + * maintaining multiple copies of an object ID. The object ID can be + * incremented when a copy is made. Each copy of the ID can then be + * safely closed or decremented and the HDF5 object will be closed + * when the reference count for that that object drops to zero. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Idec_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative current reference count of the object + * identifier if successful; otherwise a negative value is returned. + * + * \details H5Iget_ref() retrieves the reference count of the object identified + * by \p id. + * + * The reference count for an object identifier is attached to the + * information about an object in memory and has no relation to the + * number of links to an object on disk. + * + * The function H5Iis_valid() is used to determine whether a specific + * object identifier is valid. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Iget_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Creates and returns a new ID type + * + * \param[in] hash_size Minimum hash table size (in entries) used to store IDs + * for the new type + * \param[in] reserved Number of reserved IDs for the new type + * \param[in] free_func Function used to deallocate space for a single ID + * + * \return Returns the type identifier on success, negative on failure. + * + * \details H5Iregister_type() allocates space for a new ID type and returns an + * identifier for it. + * + * The \p hash_size parameter indicates the minimum size of the hash + * table used to store IDs in the new type. + * + * The \p reserved parameter indicates the number of IDs in this new + * type to be reserved. Reserved IDs are valid IDs which are not + * associated with any storage within the library. + * + * The \p free_func parameter is a function pointer to a function + * which returns an herr_t and accepts a \c void*. The purpose of this + * function is to deallocate memory for a single ID. It will be called + * by H5Iclear_type() and H5Idestroy_type() on each ID. This function + * is NOT called by H5Iremove_verify(). The \c void* will be the same + * pointer which was passed in to the H5Iregister() function. The \p + * free_func function should return 0 on success and -1 on failure. + * + */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); -H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); -H5_DLL herr_t H5Idestroy_type(H5I_type_t type); -H5_DLL int H5Iinc_type_ref(H5I_type_t type); -H5_DLL int H5Idec_type_ref(H5I_type_t type); -H5_DLL int H5Iget_type_ref(H5I_type_t type); -H5_DLL void * H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); -H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); -H5_DLL htri_t H5Itype_exists(H5I_type_t type); -H5_DLL htri_t H5Iis_valid(hid_t id); +/** + * \ingroup H5I + * + * \brief Deletes all identifiers of the given type + * + * \param[in] type Identifier of identifier type which is to be cleared of identifiers + * \param[in] force Whether or not to force deletion of all identifiers + * + * \return \herr_t + * + * \details H5Iclear_type() deletes all identifiers of the type identified by + * the argument \p type. + * + * The identifier type's free function is first called on all of these + * identifiers to free their memory, then they are removed from the + * type. + * + * If the \p force flag is set to false, only those identifiers whose + * reference counts are equal to 1 will be deleted, and all other + * identifiers will be entirely unchanged. If the force flag is true, + * all identifiers of this type will be deleted. + * + */ +H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); +/** + * \ingroup H5I + * + * \brief Removes an identifier type and all identifiers within that type + * + * \param[in] type Identifier of identifier type which is to be destroyed + * + * \return \herr_t + * + * \details H5Idestroy_type deletes an entire identifier type \p type. All + * identifiers of this type are destroyed and no new identifiers of + * this type can be registered. + * + * The type’s free function is called on all of the identifiers which + * are deleted by this function, freeing their memory. In addition, + * all memory used by this type’s hash table is freed. + * + * Since the H5I_type_t values of destroyed identifier types are + * reused when new types are registered, it is a good idea to set the + * variable holding the value of the destroyed type to #H5I_UNINIT. + * + */ +H5_DLL herr_t H5Idestroy_type(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Increments the reference count on an ID type + * + * \param[in] type The identifier of the type whose reference count is to be incremented + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Iinc_type_ref() increments the reference count on an ID type. The + * reference count is used by the library to indicate when an ID type + * can be destroyed. + * + * The type parameter is the identifier for the ID type whose + * reference count is to be incremented. This identifier must have + * been created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Iinc_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Decrements the reference count on an identifier type + * + * \param[in] type The identifier of the type whose reference count is to be decremented + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Idec_type_ref() decrements the reference count on an identifier + * type. The reference count is used by the library to indicate when + * an identifier type can be destroyed. If the reference count reaches + * zero, this function will destroy it. + * + * The type parameter is the identifier for the identifier type whose + * reference count is to be decremented. This identifier must have + * been created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Idec_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Retrieves the reference count on an ID type + * + * \param[in] type The identifier of the type whose reference count is to be retieved + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Iget_type_ref() retrieves the reference count on an ID type. The + * reference count is used by the library to indicate when an ID type + * can be destroyed. + * + * The type parameter is the identifier for the ID type whose + * reference count is to be retrieved. This identifier must have been + * created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Iget_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Finds the memory referred to by an ID within the given ID type such + * that some criterion is satisfied + * + * \param[in] type The identifier of the type to be searched + * \param[in] func The function defining the search criteria + * \param[in] key A key for the search function + * + * \return Returns a pointer to the object which satisfies the search function + * on success, NULL on failure. + * + * \details H5Isearch() searches through a given ID type to find an object that + * satisfies the criteria defined by \p func. If such an object is + * found, the pointer to the memory containing this object is + * returned. Otherwise, NULL is returned. To do this, \p func is + * called on every member of type \p type. The first member to satisfy + * \p func is returned. + * + * The \p type parameter is the identifier for the ID type which is to + * be searched. This identifier must have been created by a call to + * H5Iregister_type(). + * + * The parameter \p func is a function pointer to a function which + * takes three parameters. The first parameter is a \c void* and will + * be a pointer to the object to be tested. This is the same object + * that was placed in storage using H5Iregister(). The second + * parameter is a hid_t and is the ID of the object to be tested. The + * last parameter is a \c void*. This is the \p key parameter and can + * be used however the user finds helpful, or it can be ignored if it + * is not needed. \p func returns 0 if the object it is testing does + * not pass its criteria. A non-zero value should be returned if the + * object does pass its criteria. H5I_search_func_t is defined in + * H5Ipublic.h and is shown below. + * \snippet this H5I_search_func_t_snip + * The \p key parameter will be passed to the search function as a + * parameter. It can be used to further define the search at run-time. + * + */ +H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); +/** + * \ingroup H5I + * + * \brief Returns the number of identifiers in a given identifier type + * + * \param[in] type The identifier type + * \param[out] num_members Number of identifiers of the specified identifier type + * + * \return \herr_t + * + * \details H5Inmembers() returns the number of identifiers of the identifier + * type specified in \p type. + * + * The number of identifiers is returned in \p num_members. If no + * identifiers of this type have been registered, the type does not + * exist, or it has been destroyed, \p num_members is returned with + * the value 0. + * + */ +H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); +/** + * \ingroup H5I + * + * \brief Determines whether an identifier type is registered + * + * \param[in] type Identifier type + * + * \return \htri_t + * + * \details H5Itype_exists() determines whether the given identifier type, + * \p type, is registered with the library. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Itype_exists(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Determines whether an identifier is valid + * + * \obj_id{id} + * + * \return \htri_t + * + * \details H5Iis_valid() determines whether the identifier \p id is valid. + * + * \details Valid identifiers are those that have been obtained by an + * application and can still be used to access the original target. + * Examples of invalid identifiers include: + * \li Out of range values: negative, for example + * \li Previously-valid identifiers that have been released: + * for example, a dataset identifier for which the dataset has + * been closed + * + * H5Iis_valid() can be used with any type of identifier: object + * identifier, property list identifier, attribute identifier, error + * message identifier, etc. When necessary, a call to H5Iget_type() + * can determine the type of the object that \p id identifies. + * + * \since 1.8.3 + * + */ +H5_DLL htri_t H5Iis_valid(hid_t id); #ifdef __cplusplus } diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index 861b716..d78efda 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -33,14 +33,21 @@ /* Public Macros */ /*****************/ -/* Maximum length of a link's name */ -/* (encoded in a 32-bit unsigned integer) */ +/** + * \brief Maximum length of a link's name + * + * The maximum length of a link's name is encoded in a 32-bit unsigned integer. + */ #define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */ -/* Macro to indicate operation occurs on same location */ +/** + * \brief Macro to indicate operation occurs on same location + */ #define H5L_SAME_LOC (hid_t)0 -/* Current version of the H5L_class_t struct */ +/** + * \brief Current version of the H5L_class_t struct + */ #define H5L_LINK_CLASS_T_VERS 0 #ifdef __cplusplus @@ -51,85 +58,119 @@ extern "C" { /* Public Typedefs */ /*******************/ -/* Link class types. - * Values less than 64 are reserved for the HDF5 library's internal use. - * Values 64 to 255 are for "user-defined" link class types; these types are - * defined by HDF5 but their behavior can be overridden by users. - * Users who want to create new classes of links should contact the HDF5 - * development team at help@hdfgroup.org. - * These values can never change because they appear in HDF5 files. +/** + * \brief Link class types. + * + * Values less than 64 are reserved for the HDF5 library's internal use. Values + * 64 to 255 are for "user-defined" link class types; these types are defined + * by HDF5 but their behavior can be overridden by users. Users who want to + * create new classes of links should contact the HDF5 development team at + * mailto:help@hdfgroup.org. These values can never change because they appear + * in HDF5 files. */ typedef enum { - H5L_TYPE_ERROR = (-1), /* Invalid link type id */ - H5L_TYPE_HARD = 0, /* Hard link id */ - H5L_TYPE_SOFT = 1, /* Soft link id */ - H5L_TYPE_EXTERNAL = 64, /* External link id */ - H5L_TYPE_MAX = 255 /* Maximum link type id */ + H5L_TYPE_ERROR = (-1), /**< Invalid link type id */ + H5L_TYPE_HARD = 0, /**< Hard link id */ + H5L_TYPE_SOFT = 1, /**< Soft link id */ + H5L_TYPE_EXTERNAL = 64, /**< External link id */ + H5L_TYPE_MAX = 255 /**< Maximum link type id */ } H5L_type_t; -/* Maximum value link value for "built-in" link types */ +/** + * \brief Maximum value link value for "built-in" link types + */ #define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT -/* Link ids at or above this value are "user-defined" link types. */ +/** + * \brief Link ids at or above this value are "user-defined" link types. + */ #define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL -/* Information struct for link (for H5Lget_info/H5Lget_info_by_idx) */ +/** + * \brief Information struct for links + */ +//! <!-- [H5L_info_t_snip] --> typedef struct { - H5L_type_t type; /* Type of link */ - hbool_t corder_valid; /* Indicate if creation order is valid */ - int64_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of link name */ + H5L_type_t type; /**< Type of link */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + int64_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of link name */ union { - haddr_t address; /* Address hard link points to */ - size_t val_size; /* Size of a soft link or UD link value */ + haddr_t address; /**< Address hard link points to */ + size_t val_size; /**< Size of a soft link or user-defined link value */ } u; } H5L_info_t; +//! <!-- [H5L_info_t_snip] --> /* The H5L_class_t struct can be used to override the behavior of a * "user-defined" link class. Users should populate the struct with callback * functions defined below. */ /* Callback prototypes for user-defined links */ -/* Link creation callback */ +/** + * \brief Link creation callback + */ typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id); - -/* Callback for when the link is moved */ +/** + * \brief Callback for link move + */ typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size); - -/* Callback for when the link is copied */ +/** + * \brief Callback for link copy + */ typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size); -/* Callback during link traversal */ +/** + * \brief Callback during link traversal + */ typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id); - -/* Callback for when the link is deleted */ +/** + * \brief Callback for link deletion + */ typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, size_t lnkdata_size); - -/* Callback for querying the link */ -/* Returns the size of the buffer needed */ +/** + * \brief Callback for querying the link. + * + * Returns the size of the buffer needed. + */ typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, void *buf /*out*/, size_t buf_size); /* User-defined link types */ +/** + * \brief Link prototype + * + * The H5L_class_t struct can be used to override the behavior of a + * "user-defined" link class. Users should populate the struct with callback + * functions defined elsewhere. + */ +//! <!-- [H5L_class_t_snip] --> typedef struct { - int version; /* Version number of this struct */ - H5L_type_t id; /* Link type ID */ - const char * comment; /* Comment for debugging */ - H5L_create_func_t create_func; /* Callback during link creation */ - H5L_move_func_t move_func; /* Callback after moving link */ - H5L_copy_func_t copy_func; /* Callback after copying link */ - H5L_traverse_func_t trav_func; /* Callback during link traversal */ - H5L_delete_func_t del_func; /* Callback for link deletion */ - H5L_query_func_t query_func; /* Callback for queries */ + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char * comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ } H5L_class_t; +//! <!-- [H5L_class_t_snip] --> -/* Prototype for H5Literate/H5Literate_by_name() operator */ +/** + * \brief Prototype for H5Literate(), H5Literate_by_name() operator + */ +//! <!-- [H5L_iterate_t_snip] --> typedef herr_t (*H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info, void *op_data); +//! <!-- [H5L_iterate_t_snip] --> -/* Callback for external link traversal */ +/** + * \brief Callback for external link traversal + */ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name, const char *child_file_name, const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data); @@ -141,48 +182,1401 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char /*********************/ /* Public Prototypes */ /*********************/ +/** + * \ingroup H5L + * + * \brief Moves a link within an HDF5 file + * + * \fgdta_loc_id{src_loc} + * \param[in] src_name Original link name + * \fgdta_loc_id{dst_loc} + * \param[in] dst_name New link name + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Lmove() moves a link within an HDF5 file. The original link, + * \p src_name, is removed from \p src_loc and the new link, + * \p dst_name, is inserted at dst_loc. This change is + * accomplished as an atomic operation. + * + * \p src_loc and \p src_name identify the original link. + * \p src_loc is the original location identifier; \p src_name is + * the path to the link and is interpreted relative to \p src_loc. + * + * \p dst_loc and \p dst_name identify the new link. \p dst_loc is + * either a file or group identifier; \p dst_name is the path to + * the link and is interpreted relative to \p dst_loc. + * + * \p lcpl_id and \p lapl_id are the link creation and link access + * property lists, respectively, associated with the new link, + * \p dst_name. + * + * Through these property lists, several properties are available to + * govern the behavior of H5Lmove(). The property controlling creation + * of missing intermediate groups is set in the link creation property + * list with H5Pset_create_intermediate_group(); H5Lmove() ignores any + * other properties in the link creation property list. Properties + * controlling character encoding, link traversals, and external link + * prefixes are set in the link access property list with + * H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(), + * respectively. + * + * \note Note that H5Lmove() does not modify the value of the link; the new + * link points to the same object as the original link pointed to. + * Furthermore, if the object pointed to by the original link was already + * open with a valid object identifier, that identifier will remain valid + * after the call to H5Lmove(). + * + * \attention Exercise care in moving links as it is possible to render data in + * a file inaccessible with H5Lmove(). If the link being moved is on + * the only path leading to an HDF5 object, that object may become + * permanently inaccessible in the file. + * + * \since 1.8.0 + * + *------------------------------------------------------------------------- + */ H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates an identical copy of a link with the same creation time and + * target. The new link can have a different name and be in a different + * location than the original. + * + * \fgdt_loc_id{src_loc} + * \param[in] src_name Name of the link to be copied + * \fgdt_loc_id{dst_loc} + * \param[in] dst_name Name to be assigned to the new copy + * \lcpl_id + * \lapl_id + * \return \herr_t + * + * \details H5Lcopy() copies the link specified by \p src_name from the location + * specified by \p src_loc_id to the location specified by + * \p dst_loc_id. The new copy of the link is created with the name + * \p dst_name. + * + * If \p dst_loc_id is a file identifier, \p dst_name will be + * interpreted relative to that file’s root group. + * + * The new link is created with the creation and access property lists + * specified by \p lcpl_id and \p lapl_id. The interpretation of + * \p lcpl_id is limited in the manner described in the next paragraph. + * + * H5Lcopy() retains the creation time and the target of the original + * link. However, since the link may be renamed, the character + * encoding is that specified in \p lcpl_id rather than that of the + * original link. Other link creation properties are ignored. + * + * If the link is a soft link, also known as a symbolic link, its + * target is interpreted relative to the location of the copy. + * + * Several properties are available to govern the behavior of + * H5Lcopy(). These properties are set in the link creation and access + * property lists, \p lcpl_id and \p lapl_id, respectively. The + * property controlling creation of missing intermediate groups is set + * in the link creation property list with + * H5Pset_create_intermediate_group(); this function ignores any + * other properties in the link creation property list. Properties + * controlling character encoding, link traversals, and external link + * prefixes are set in the link access property list with + * H5Pset_char_encoding(), H5Pset_nlinks(), and + * H5Pset_elink_prefix(). + * + * \note H5Lcopy() does not affect the object that the link points to. + * + * \attention H5Lcopy() cannot copy hard links across files as a hard link is + * not valid without a target object; to copy objects from one file + * to another, see H5Ocopy(). + * + * \see H5Ocopy() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates a hard link to an object + * + * \fgdta_loc_id{cur_loc} + * \param[in] cur_name Name of the target object, which must already exist + * \fgdta_loc_id{dst_loc} + * \param[in] dst_name The name of the new link + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Lcreate_hard() creates a new hard link to a pre-existing object + * in an HDF5 file. + * + * \p cur_loc and \p cur_name specify the location + * and name, respectively, of the target object, i.e., the object that + * the new hard link points to. \p dst_loc and \p dst_name specify the + * location and name, respectively, of the new hard link. + * + * \p cur_name and \p dst_name are interpreted relative to \p cur_loc + * and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the + * same location, the HDF5 macro #H5L_SAME_LOC can be used for either + * parameter (but not both). + * + * \p lcpl_id and \p lapl_id are the link creation and access property + * lists associated with the new link. + * + * \note Hard and soft links are for use only if the target object is in the + * current file. If the desired target object is in a different file from + * the new link, an external link may be created with + * H5Lcreate_external(). + * + * \note The HDF5 library keeps a count of all hard links pointing to an + * object; if the hard link count reaches zero (0), the object will be + * deleted from the file. Creating new hard links to an object will + * prevent it from being deleted if other links are removed. The + * library maintains no similar count for soft links and they can dangle. + * + * \note The new link may be one of many that point to that object. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates a soft link + * + * \param[in] link_target An HDF5 path name + * \fgdta_loc_id{link_loc_id} + * \param[in] link_name The name of the new link + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Lcreate_soft() creates a new soft link to an object in an HDF5 + * file. + * + * \p link_target specifies the HDF5 path name the soft link contains. + * \p link_target can be an arbitrary HDF5 path name and is + * interpreted only at lookup time. This path may be absolute in the + * file or relative to \p link_loc_id. + * + * \p link_loc_id and \p link_name specify the location and name, + * respectively, of the new soft link. \p link_name is interpreted + * relative to \p link_loc_id and must contain only the name of the soft + * link; \p link_name may not contain any additional path elements. + * + * If \p link_loc_id is a group identifier, the object pointed to by + * \p link_name will be accessed as a member of that group. If + * \p link_loc_id is a file identifier, the object will be accessed as a + * member of the file's root group. + * + * \p lcpl_id and \p lapl_id are the link creation and access property + * lists associated with the new link. + * + * For instance, if target_path is \c ./foo, \p link_loc_id specifies + * \c ./x/y/bar, and the name of the new link is \c new_link, then a + * subsequent request for \c ./x/y/bar/new_link will return same the + * object as would be found at \c ./foo. + * + * \note H5Lcreate_soft() is for use only if the target object is in the + * current file. If the desired target object is in a different file from + * the new link, use H5Lcreate_external() to create an external link. + * + * \note Soft links and external links are also known as symbolic links as they + * use a name to point to an object; hard links employ an object’s + * address in the file. + * + * \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle, + * meaning that the target object need not exist at the time that the + * link is created. + * + * \note The HDF5 library does not keep a count of soft links as it does of + * hard links. + * + * \note The new link may be one of many that point to that object. + * + * \see H5Lcreate_hard(), H5Lcreate_external() + * + * \since 1.8.0 + * + + */ H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Removes a link from a group + * + * \fgdta_loc_id + * \param[in] name Name of the link to delete + * \lapl_id + * + * \return \herr_t + * + * \details H5Ldelete() removes the link specified by \p name from the location + * \p loc_id. + * + * If the link being removed is a hard link, H5Ldelete() also + * decrements the link count for the object to which name points. + * Unless there is a duplicate hard link in that group, this action + * removes the object to which name points from the group that + * previously contained it. + * + * Object headers keep track of how many hard links refer to an + * object; when the hard link count, also referred to as the reference + * count, reaches zero, the object can be removed from the file. The + * file space associated will then be released, i.e., identified in + * memory as freespace. Objects which are open are not removed until + * all identifiers to the object are closed. + * + * \attention Exercise caution in the use of H5Ldelete(); if the link being + * removed is on the only path leading to an HDF5 object, that + * object may become permanently inaccessible in the file. + * + * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Removes the \Emph{n}-th link in a group + * + * \fgdta_loc_id + * \param[in] group_name Name of subject group + * \param[in] idx_type Index or field which determines the order + * \param[in] order Order within field or index + * \param[in] n Link for which to retrieve information + * \lapl_id + * + * \return \herr_t + * + * \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group + * according to the specified order, \p order, in the specified index, + * \p index. + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * \see H5Ldelete() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Returns the value of a link + * + * \fgdta_loc_id + * \param[in] name Link name + * \param[out] buf The buffer to hold the link value + * \param[in] size Maximum number of bytes of link value to be returned + * \lapl_id + * + * \return \herr_t + * + * \details H5Lget_val() returns tha value of link \p name. For smbolic links, + * this is the path to which the link points, including the null + * terminator. For external and user-defined links, it is the link + * buffer. + * + * \p size is the size of \p buf and should be the size of the link + * value being returned. This size value can be determined through a + * call to H5Lget_info(); it is returned in the \c val_size field of + * the \ref H5L_info_t \c struct. + * + * If \p size is smaller than the size of the returned value, then the + * string stored in \p buf will be truncated to \p size bytes. For + * soft links, this means that the value will not be null terminated. + * + * In the case of external links, the target file and object names are + * extracted from \p buf by calling H5Lunpack_elink_val(). + * + * The link class of link \p name can be determined with a call to + * H5Lget_info(). + * + * \p lapl_id specifies the link access property list associated with + * the link \p name. In the general case, when default link access + * properties are acceptable, this can be passed in as #H5P_DEFAULT. An + * example of a situation that requires a non-default link access + * property list is when the link is an external link; an external + * link may require that a link prefix be set in a link access + * property list (see H5Pset_elink_prefix()). + * + * This function should be used only after H5Lget_info() has been + * called to verify that \p name is a symbolic link. This can be + * deteremined from the \c link_type field of the \ref H5L_info_t + * \c struct. + * + * \note This function will fail if called on a hard link. + * + * \see H5Lget_val_by_idx() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size_t size, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves value of the \Emph{n}-th link in a group, according to the order within an index + * + * \fgdta_loc_id + * \param[in] group_name Group name + * \param[in] idx_type Type of index + * \param[in] order Order within field or index + * \param[in] n Link position for which to retrieve information + * \param[out] buf The buffer to hold the link value + * \param[in] size Maximum number of bytes of link value to be returned + * \lapl_id + * + * \return \herr_t + * + * \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in + * a group, according to the specified order, \p order, within an + * index, \p index. + * + * For soft links, the value is an HDF5 path name. + * + * For external links, this is a compound value containing file and + * path name information; to use this external link information, it + * must first be decoded with H5Lunpack_elink_val() + * + * For user-defined links, this value will be described in the + * definition of the user-defined link type. + * + * \p loc_id specifies the location identifier of the group specified + * by \p group_name. + * + * \p group_name specifies the group in which the link exists. If + * \p loc_id already specifies the group in which the link exists, + * \p group_name must be a dot (\c .). + * + * The size in bytes of link_val is specified in \p size. The size + * value can be determined through a call to H5Lget_info_by_idx(); it + * is returned in the \c val_size field of the \ref H5L_info_t + * \c struct. If + * size is smaller than the size of the returned value, then the + * string stored in link_val will be truncated to size bytes. For soft + * links, this means that the value will not be null terminated. + * + * If the type of the link is unknown or uncertain, H5Lget_val_by_idx() + * should be called only after the type has been determined via a call + * to H5Lget_info_by_idx(). + * + * \note This function will fail if called on a hard link. + * + * \see H5Lget_val() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, void *buf /*out*/, size_t size, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Determines whether a link with the specified name exists in a group + * + * \fgdta_loc_id + * \param[in] name Link name + * \lapl_id + * + * \return \herr_t + * + * \details H5Lexists() allows an application to determine whether the link \p + * name exists in the location specified by \p loc_id. The link may be + * of any type; only the presence of a link with that name is checked. + * + * Note that H5Lexists() verifies only that the target link exists. If + * name includes either a relative path or an absolute path to the + * target link, intermediate steps along the path must be verified + * before the existence of the target link can be safely checked. If + * the path is not verified and an intermediate element of the path + * does not exist, H5Lexists() will fail. The example in the next + * paragraph illustrates one step-by-step method for verifying the + * existence of a link with a relative or absolute path. + * + * \Bold{Example:} Use the following steps to verify the existence of + * the link \c datasetD in the \c group group1/group2/softlink_to_group3/, + * where \c group1 is a member of the group specified by \c loc_id: + * + * 1. First use H5Lexists() to verify that \c group1 exists. + * 2. If \c group1 exists, use H5Lexists() again, this time with name + * set to \c group1/group2, to verify that \c group2 exists. + * 3. If \c group2 exists, use H5Lexists() with name set to + * \c group1/group2/softlink_to_group3 to verify that + * \c softlink_to_group3 exists. + * 4. If \c softlink_to_group3 exists, you can now safely use + * H5Lexists() with \c name set to + * \c group1/group2/softlink_to_group3/datasetD to verify that the + * target link, \c datasetD, exists. + * + * If the link to be verified is specified with an absolute path, the + * same approach should be used, but starting with the first link in + * the file’s root group. For instance, if \c datasetD were in + * \c /group1/group2/softlink_to_group3, the first call to H5Lexists() + * would have name set to \c /group1. + * + * Note that this is an outline and does not include all necessary + * details. Depending on circumstances, for example, you may need to + * verify that an intermediate link points to a group and that a soft + * link points to an existing target. + * + * \note The behavior of H5Lexists() was changed in the 1.10 release in the + * case where the root group, \c "/", is the name of the link. This + * change is described below: + * <ol> + * <li>Let \c file denote a valid HDF5 file identifier, and let \c lapl + * denote a valid link access property list identifier. A call to + * H5Lexists() with arguments \c file, \c "/", and \c lapl + * returns a positive value; in other words, + * \Code{H5Lexists(file, "/", lapl)} returns a positive value. + * In HDF5 version 1.8.16, this function returns 0.</li> + * <li>Let \c root denote a valid HDF5 group identifier that refers to the + * root group of an HDF5 file, and let \c lapl denote a valid link + * access property list identifier. A call to H5Lexists() with + * arguments c root, \c "/", and \c lapl returns a positive value; + * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive + * value. In HDF5 version 1.8.16, this function returns 0.</li> + * </ol> + * Note that the function accepts link names and path names. This is + * potentially misleading to callers, and we plan to separate the + * functionality for link names and path names in a future release. + * + * \attention H5Lexists() checks the existence of only the final element in a + * relative or absolute path; it does not check any other path + * elements. The function will therefore fail when both of the + * following conditions exist: + * - \c name is not local to the group specified by \c loc_id or, + * if \c loc_id is something other than a group identifier, \c name + * is not local to the root group. + * - Any element of the relative path or absolute path in name, + * except the target link, does not exist. + * + * \version 1.10.0 Function behavior changed in this release. (See the note.) + * \since 1.8.0 + * + */ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); -H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo /*out*/, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Returns information about a link + * + * \fgdta_loc_id + * \param[in] name Link name + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \details H5Lget_info() returns information about the specified link through + * the \p linfo argument. + * + * The location identifier, \p loc_id, specifies the location of the + * link. A link name, \p name, interpreted relative to \p loc_id, + * specifies the link being queried. + * + * \p lapl_id is the link access property list associated with the + * link \p name. In the general case, when default link access + * properties are acceptable, this can be passed in as #H5P_DEFAULT. + * An example of a situation that requires a non-default link access + * property list is when the link is an external link; an external + * link may require that a link prefix be set in a link access + * property list (see H5Pset_elink_prefix()). + * + * H5Lget_info() returns information about name in the data structure + * \ref H5L_info_t, which is described below and defined in + * H5Lpublic.h. This structure is returned in the buffer \p linfo. + * \snippet this H5L_info_t_snip + * In the above struct, type specifies the link class. Valid values + * include the following: + * \link_types + * There will be additional valid values if user-defined links have + * been registered. + * + * \c corder specifies the link’s creation order position while + * \c corder_valid indicates whether the value in \c corder is valid. + * + * If \c corder_valid is \c TRUE, the value in \c corder is known to + * be valid; if \c corder_valid is \c FALSE, the value in \c corder is + * presumed to be invalid; + * + * \c corder starts at zero (0) and is incremented by one (1) as new + * links are created. But higher-numbered entries are not adjusted + * when a lower-numbered link is deleted; the deleted link’s creation + * order position is simply left vacant. In such situations, the value + * of \c corder for the last link created will be larger than the + * number of links remaining in the group. + * + * \c cset specifies the character set in which the link name is + * encoded. Valid values include the following: + * \csets + * This value is set with H5Pset_char_encoding(). + * + * \c address and \c val_size are returned for hard and symbolic + * links, respectively. Symbolic links include soft and external links + * and some user-defined links. + * + * If the link is a hard link, \c address specifies the file address + * that the link points to. + * + * If the link is a symbolic link, \c val_size will be the length of + * the link value, e.g., the length of the HDF5 path name with a null + * terminator. + * + * \version 1.8.2 Fortran subroutine added in this release. + * \version 1.8.4 Fortran subroutine syntax changed in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves metadata for a link in a group, according to the order + * within a field or index + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in] n Link position for which to retrieve information + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \details H5get_info_by_idx() returns the metadata for a link in a group + * according to a specified field or index and a specified order. + * + * The link for which information is to be returned is specified by \p + * idx_type, \p order, and \p n as follows: + * + * - \p idx_type specifies the field by which the links in \p + * group_name are ordered. The links may be indexed on this field, + * in which case operations seeking specific links are likely to + * complete more quickly. + * - \p order specifies the order in which + * the links are to be referenced for the purposes of this function. + * - \p n specifies the position of the subject link. Note that this + * count is zero-based; 0 (zero) indicates that the function will + * return the value of the first link; if \p n is 5, the function + * will return the value of the sixth link; etc. + * + * For example, assume that \p idx_type, \p order, and \p n are + * #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME + * indicates that the links are accessed in lexicographic order by + * their names. #H5_ITER_DEC specifies that the list be traversed in + * reverse order, or in decremented order. And 5 specifies that this + * call to the function will return the metadata for the 6th link + * (\c n + 1) from the end. + * + * See H5Literate() for a list of valid values and further discussion + * regarding \p idx_type and \p order. + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * \version 1.8.4 Fortran subroutine syntax changed in this release. + * \version 1.8.2 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, H5L_info_t *linfo /*out*/, hid_t lapl_id); + H5_iter_order_t order, hsize_t n, H5L_info_t *linfo, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves name of the \Emph{n}-th link in a group, according to the + * order within a specified field or index + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in] n Link position for which to retrieve information + * \param[out] name Buffer in which link name is returned + * \param[in] size Size in bytes of \p name + * \lapl_id + * + * \return Returns the size of the link name if successful; otherwise returns a + * negative value. + * + * \details H5get_name_by_idx() retrieves the name of the \Emph{n}-th link in a + * group, according to the specified order, \p order, within a specified + * field or index, \p idx_type. + * + * \p idx_type specifies the index that is used. Valid values include + * the following: + * \indexes + * + * \p order specifies the order in which objects are inspected along + * the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * The size in bytes of name is specified in \p size. If \p size is + * unknown, it can be determined via an initial H5Lget_name_by_idx() + * call with name set to NULL; the function's return value will be the + * size of the name. + * + * \note Please note that in order for the specified index to correspond to the + * creation order index, \p order must be set to #H5_ITER_INC or + * #H5_ITER_DEC when calling H5Lget_name_by_idx(). \note The index \p n + * passed to H5Lget_name_by_idx() is the index of the link within the + * link table, sorted according to \p order and \p idx_type. If order is + * #H5_ITER_NATIVE, then the link table is not sorted, and it does not + * matter what \p idx_type is. Specifying #H5_ITER_NATIVE does not + * guarantee any particular order, only that it remains consistent. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size, hid_t lapl_id); -H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, - H5L_iterate_t op, void *op_data); -H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data, - hid_t lapl_id); -H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, - void *op_data); -H5_DLL herr_t H5Lvisit_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id); +/** + * \ingroup TRAV + * + * \brief Iterates over links in a group, with user callback routine, + * according to the order within an index. + * + * \group_id{grp_id} + * \idx_type + * \order + * \param[in,out] idx Pointer to an iteration index to allow + * continuing a previous iteration + * \op + * \op_data + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Literate() iterates through the links in a file or + * group, \p group_id, in the order of the specified + * index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate() does not recursively follow links into + * subgroups of the specified group. + * + * Three parameters are used to manage progress of the iteration: + * \p idx_type, \p order, and \p idx_p. + * + * \p idx_type specifies the index to be used. If the links have + * not been indexed by the index type, they will first be sorted by + * that index then the iteration will begin; if the links have been + * so indexed, the sorting step will be unnecessary, so the iteration + * may begin more quickly. + * + * \p order specifies the order in which objects are to be inspected + * along the index \p idx_type. + * + * \p idx_p tracks the iteration and allows an iteration to be + * resumed if it was stopped before all members were processed. It is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \p op_data is a user-defined pointer to the data required to + * process links in the course of the iteration. This pointer is + * passed back to each step of the iteration in the \p op callback + * function's \p op_data parameter. \p op is invoked for each link + * encounter. + * + * \p op_data is passed to and from each iteration and can be used to + * supply or aggregate information across iterations. + * + * \remark Same pattern of behavior as H5Giterate(). + * + * \note This function is also available through the H5Literate() macro. + * + * \warning The behavior of H5Literate() is undefined if the link + * membership of \p group_id changes during the iteration. + * This does not limit the ability to change link destinations + * while iterating, but caution is advised. + * + * + * \since 1.8.0 + * + * \see H5Literate_by_name(), H5Lvisit(), H5Lvisit_by_name() + * + */ +H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, + H5L_iterate_t op, void *op_data); +/** + * \ingroup TRAV + * + * \brief Iterates through links in a group by its name + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in,out] idx iteration position at which to start (\Emph{IN}) or + * position at which an interrupted iteration may be restarted + * (\Emph{OUT}) + * \op + * \op_data + * \lapl_id + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Literate_by_name() iterates through the links in a group + * specified by \p loc_id and \p group_name, in the order of the + * specified index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate_by_name() does not recursively follow links into + * subgroups of the specified group. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p idx allows an interrupted iteration to be resumed; it is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \note H5Literate_by_name() is not recursive. In particular, if a member of + * \p group_name is found to be a group, call it \c subgroup_a, + * H5Literate_by_name() does not examine the members of \c subgroup_a. + * When recursive iteration is required, the application must handle the + * recursion, explicitly calling H5Literate_by_name1() on discovered + * subgroups. + * + * \note H5Literate_by_name() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function’s + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * + * \note H5Literate_by_name() is the same as H5Giterate(), except that + * H5Giterate() always proceeds in lexicographic order. + * + * \version 1.8.8 Fortran subroutine added. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data, + hid_t lapl_id); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \group_id{grp_id} + * \idx_type + * \order + * \op + * \op_data + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Lvisit() is a recursive iteration function to visit all links in + * and below a group in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all of + * those links or a dynamically selected subset. For non-recursive + * iteration across the members of a group, see H5Literate(). + * + * The group serving as the root of the iteration is specified by its + * group or file identifier, \p group_id. + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p op is a callback function of type \ref H5L_iterate_t that is invoked + * for each link encountered. + * \snippet this H5L_iterate_t_snip + * + * The \ref H5L_info_t struct is defined (in H5Lpublic.h) as follows: + * \snippet this H5L_info_t_snip + * + * The possible return values from the callback function, and the + * effect of each, are as follows: + * \li Zero causes the visit iterator to continue, returning zero when + * all group members have been processed. + * \li A positive value causes the visit iterator to immediately + * return that positive value, indicating short-circuit success. + * \li A negative value causes the visit iterator to immediately + * return that value, indicating failure. + * + * The H5Lvisit() \p op_data parameter is a user-defined pointer to + * the data required to process links in the course of the iteration. + * This pointer is passed back to each step of the iteration in the + * \p op callback function's \p op_data parameter. + * + * H5Lvisit() and H5Ovisit() are companion functions: one for + * examining and operating on links; the other for examining and + * operating on the objects that those links point to. Both functions + * ensure that by the time the function completes successfully, every + * link or object below the specified point in the file has been + * presented to the application for whatever processing the + * application requires. + * + * \since 1.8.0 + * + * \see H5Literate() + * + */ +H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, + void *op_data); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \op + * \op_data + * \lapl_id + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Lvisit_by_name() is a recursive iteration function to visit all + * links in and below a group in an HDF5 file, thus providing a + * mechanism for an application to perform a common set of operations + * across all of those links or a dynamically selected subset. For + * non-recursive iteration across the members of a group, see + * H5Literate(). + * + * The group serving as the root of the iteration is specified by the + * \p loc_id / \p group_name parameter pair. \p loc_id specifies a + * file or group; group_name specifies either a group in the file + * (with an absolute name based in the file’s root group) or a group + * relative to \p loc_id. If \p loc_id fully specifies the group that + * is to serve as the root of the iteration, group_name should be '.' + * (a dot). (Note that when \p loc_id fully specifies the the group + * that is to serve as the root of the iteration, the user may wish to + * consider using H5Lvisit() instead of H5Lvisit_by_name().) + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecesary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * The \p op callback function, the related \ref H5L_info_t + * \c struct, and the effect that the callback function's return value + * has on the application are described in H5Lvisit(). + * + * The H5Lvisit_by_name() \p op_data parameter is a user-defined + * pointer to the data required to process links in the course of the + * iteration. This pointer is passed back to each step of the + * iteration in the callback function's \p op_data parameter. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can be + * passed in as #H5P_DEFAULT. An example of a situation that requires + * a non-default link access property list is when the link is an + * external link; an external link may require that a link prefix be + * set in a link access property list (see H5Pset_elink_prefix()). + * + * H5Lvisit_by_name() and H5Ovisit_by_name() are companion + * functions: one for examining and operating on links; the other for + * examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point in the + * file has been presented to the application for whatever processing + * the application requires. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lvisit_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, + H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id); /* UD link functions */ +/** + * \ingroup H5L + * + * \brief Creates a link of a user-defined type + * + * \loc_id{link_loc_id} + * \param[in] link_name Link name + * \param[in] link_type User-defined link class + * \param[in] udata User-supplied link information + * \param[in] udata_size Size of udata buffer + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Lcreate_ud() creates a link of user-defined type \p link_type + * named \p link_name at the location specified in \p link_loc_id with + * user-specified data \p udata. + * + * \p link_name is interpreted relative to \p link_loc_id. + * + * Valid values for the link class of the new link, \p link_type, + * include #H5L_TYPE_EXTERNAL and any user-defined link classes that + * have been registered with the library. See H5Lregister() for + * further information. + * + * The format of the information pointed to by \p udata is defined by + * the user. \p udata_size specifies the size of the \p udata buffer. + * \p udata may be NULL if \p udata_size is zero (0). + * + * The property lists specified by \p lcpl_id and \p lapl_id specify + * properties used to create and access the link. + * + * \note The external link type, #H5L_TYPE_EXTERNAL, included in the HDF5 + * library distribution, is implemented as a user-defined link type. This + * was done, in part, to provide a model for the implementation of other + * user-defined links. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5LA + * + * \brief Registers a user-defined link class or changes behavior of an + * existing class + * + * \param[in] cls Pointer to a buffer containing the struct describing the + * user-defined link class + * + * \return \herr_t + * + * \details H5Lregister() registers a class of user-defined links, or changes + * the behavior of an existing class. + * + * \p cls is a pointer to a buffer containing a copy of the + * H5L_class_t struct. This struct is defined in H5Lpublic.h as + * follows: + * \snippet this H5L_class_t_snip + * + * The class definition passed with \p cls must include at least the + * following: + * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) + * \li A link class identifier, \c class_id + * \li A traversal function, \c trav_func + * + * Remaining \c struct members are optional and may be passed as NULL. + * + * The link class passed in \c class_id must be in the user-definable + * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX + * (see the table below) and will override + * any existing link class with that identifier. + * + * As distributed, valid values of \c class_id used in HDF5 include + * the following (defined in H5Lpublic.h): + * \link_types + * + * The hard and soft link class identifiers cannot be modified or + * reassigned, but the external link class is implemented as an + * example in the user-definable link class identifier range. + * H5Lregister() is used to register additional link classes. It could + * also be used to modify the behavior of the external link class, + * though that is not recommended. + * + * The following table summarizes existing link types and values and + * the reserved and user-definable link class identifier value ranges. + * <table> + * <tr> + * <th>Link class identifier or Value range</th> + * <th>Description</th> + * <th>Link class or label</th> + * </tr> + * <tr> + * <td>0 to 63</td> + * <td>Reserved range</td> + * <td></td> + * </tr> + * <tr> + * <td>64 to 255</td> + * <td>User-definable range</td> + * <td></td> + * </tr> + * <tr> + * <td>64</td> + * <td>Minimum user-defined value</td> + * <td>#H5L_TYPE_UD_MIN</td> + * </tr> + * <tr> + * <td>64</td> + * <td>External link</td> + * <td>#H5L_TYPE_EXTERNAL</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum user-defined value</td> + * <td>#H5L_TYPE_UD_MAX</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum value</td> + * <td>#H5L_TYPE_MAX</td> + * </tr> + * <tr> + * <td>-1</td> + * <td>Error</td> + * <td>#H5L_TYPE_ERROR</td> + * </tr> + * </table> + * + * Note that HDF5 internally registers user-defined link classes only + * by the numeric value of the link class identifier. An application, + * on the other hand, will generally use a name for a user-defined + * class, if for no other purpose than as a variable name. Assume, + * for example, that a complex link type is registered with the link + * class identifier 73 and that the code includes the following + * assignment: + * \code + * H5L_TYPE_COMPLEX_A = 73 + * \endcode + * The application can refer to the link class with a term, + * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing + * the code, while HDF5 recognizes it by the more cryptic numeric + * identifier, 73. + * + * \attention Important details and considerations include the following: + * \li If you plan to distribute files or software with a + * user-defined link class, please contact the Help Desk at + * The HDF Group to help prevent collisions between \c class_id + * values. See below. + * \li As distributed with HDF5, the external link class is + * implemented as an example of a user-defined link class with + * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in + * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN + * unless you intend to overwrite or modify the behavior of + * external links. + * \li H5Lregister() can be used only with link class identifiers + * in the user-definable range (see table above). + * \li The hard and soft links defined by the HDF5 library, + * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved + * range below #H5L_TYPE_UD_MIN and cannot be redefined or + * modified. + * \li H5Lis_registered() can be used to determine whether a desired + * link class identifier is available. \Emph{Note that this + * function will tell you only whether the link class identifier + * has been registered with the installed copy of HDF5; it + * cannot tell you whether the link class has been registered + * with The HDF Group.} + * \li #H5L_TYPE_MAX is the maximum allowed value for a link type + * identifier. + * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. + * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. + * \li #H5L_TYPE_ERROR indicates that an error has occurred. + * + * \note \Bold{Registration with The HDF Group:}\n + * There are sometimes reasons to take a broader approach to registering + * a user-defined link class than just invoking H5Lregister(). For + * example: + * \li A user-defined link class is intended for use across an + * organization, among collaborators, or across a community of users. + * \li An application or library overlying HDF5 invokes a user-defined + * link class that must be shipped with the software. + * \li Files are distributed that make use of a user-defined link class. + * \li Or simply, a specific user-defined link class is thought to be + * widely useful. + * + * In such cases, you are encouraged to register that link class with + * The HDF Group's Helpdesk. The HDF Group maintains a registry of known + * user-defined link classes and tracks the selected link class + * identifiers. This registry is intended to reduce the risk of + * collisions between \c class_id values and to help coordinate the use + * of specialized link classes. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lregister(const H5L_class_t *cls); +/** + * \ingroup H5LA + * + * \brief Unregisters a class of user-defined links + * + * \param[in] id User-defined link class identifier + * + * \return \herr_t + * + * \details H5Lunregister() unregisters a class of user-defined links, + * preventing them from being traversed, queried, moved, etc. + * + * \note A link class can be re-registered using H5Lregister(). + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lunregister(H5L_type_t id); +/** + * \ingroup H5LA + * + * \brief Determines whether a class of user-defined links is registered + * + * \param[in] id User-defined link class identifier + * + * \return \htri_t + * + * \details H5Lis_registered() tests whether a user-defined link class is + * currently registered, either by the HDF5 library or by the user + * through the use of H5Lregister(). + * + * \note A link class must be registered to create new links of that type or to + * traverse existing links of that type. + * + * \since 1.8.0 + * + */ H5_DLL htri_t H5Lis_registered(H5L_type_t id); /* External link functions */ +/** + * \ingroup H5L + * + * \brief Decodes external link information + * + * \param[in] ext_linkval Buffer containing external link information + * \param[in] link_size Size, in bytes, of the \p ext_linkval buffer + * \param[out] flags External link flags, packed as a bitmap (\Emph{Reserved as + * a bitmap for flags; no flags are currently defined, so the + * only valid value * is 0.}) + * \param[out] filename Returned filename \param[out] obj_path Returned + * object path, relative to \p filename + * + * \return \herr_t + * + * \details H5Lunpack_elink_val() decodes the external link information + * returned by H5Lget_val() in the \p ext_linkval buffer. + * + * \p ext_linkval should be the buffer set by H5Lget_val() and will + * consist of two NULL-terminated strings, the filename and object + * path, one after the other. + * + * Given this buffer, H5Lunpack_elink_val() creates pointers to the + * filename and object path within the buffer and returns them in + * \p filename and \p obj_path, unless they are passed in as NULL. + * + * H5Lunpack_elink_val() requires that \p ext_linkval contain a + * concatenated pair of null-terminated strings, so use of this + * function on a string that is not an external link \p udata buffer + * may result in a segmentation fault. This failure can be avoided by + * adhering to the following procedure: + * <ol> + * <li>Call H5Lget_info() to get the link type and the size of the + * link value.<li> + * <li>Verify that the link is an external link, i.e., that its link + * type is #H5L_TYPE_EXTERNAL.</li> + * <li>Call H5Lget_val() to get the link value.</li> + * <li>Call H5Lunpack_elink_val() to unpack that value.</li> + * </ol> + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_size, unsigned *flags, const char **filename /*out*/, const char **obj_path /*out*/); +/** + * \ingroup H5L + * + * \brief Creates an external link, a soft link to an object in a different file. + * + * \param[in] file_name Name of the target file containing the target object. + * \param[in] obj_name Path within the target file to the target object + * \fgdt_loc_id{link_loc_id} + * \param[in] link_name Name of the new link, relative to \p link_loc_id + * \lcpl_id + * \lapl_id + * \return \herr_t + * + * \details H5Lcreate_external() creates a new external link. An external link + * is a soft link to an object in a different HDF5 file from the + * location of the link, i.e., to an external object. + * + * \p file_name identifies the target file containing the target + * object; \p obj_name specifies the path of the target object within + * that file. \p obj_name must be an absolute pathname in + * \p file_name, i.e., it must start at the target file’s root group, + * but it is not interpreted until an application attempts to traverse + * it. + * + * \p link_loc_id and \p link_name specify the location and name, + * respectively, of the new link. \p link_name is interpreted relative + * to \p link_loc_id. + * + * \p lcpl_id is the link creation property list used in creating the + * new link. + * + * \p lapl_id is the link access property list used in traversing the + * new link. Note that an external file opened by the traversal of an + * external link is always opened with the weak file close degree + * property setting, #H5F_CLOSE_WEAK (see H5Pset_fclose_degree()); + * any file close degree property setting in \p lapl_id is ignored. + * + * An external link behaves similarly to a soft link, and like a soft + * link in an HDF5 file, it may dangle: the target file and object + * need not exist at the time that the external link is created. + * + * When the external link \p link_name is accessed, the library will + * search for the target file \p file_name as described below: + * + * - If \p file_name is a relative pathname, the following steps are + * performed: + * - The library will get the prefix(es) set in the environment + * variable \c HDF5_EXT_PREFIX and will try to prepend each prefix + * to \p file_name to form a new \p file_name. + * - If the new \p file_name does not exist or if \c HDF5_EXT_PREFIX + * is not set, the library will get the prefix set via + * H5Pset_elink_prefix() and prepend it to \p file_name to form a + * new \p file_name. + * - If the new \p file_name does not exist or no prefix is being + * set by H5Pset_elink_prefix(), then the path of the file + * associated with \p link_loc_id is obtained. This path can be + * the absolute path or the current working directory plus the + * relative path of that file when it is created/opened. The + * library will prepend this path to \p file_name to form a new + * \p file_name. + * - If the new \p file_name does not exist, then the library will + * look for \p file_name and will return failure/success + * accordingly. + * - If \p file_name is an absolute pathname, the library will first + * try to find \p file_name. If \p file_name does not exist, + * \p file_name is stripped of directory paths to form a new + * \p file_name. The search for the new \p file_name then follows + * the same steps as described above for a relative pathname. See + * examples below illustrating how target_file_name is stripped to + * form a new \p file_name. + * + * Note that \p file_name is considered to be an absolute pathname + * when the following condition is true: + * + * - For Unix, the first character of \p file_name is a slash (\c /). + * For example, consider a \p file_name of \c /tmp/A.h5. + * If that target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * - For Windows, there are 6 cases: + * -# \p file_name is an absolute drive with absolute pathname. + * For example, consider a \p file_name of \c /tmp/A.h5. If that + * target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * -# \p file_name is an absolute pathname without specifying drive + * name. For example, consider a \p file_name of \c /tmp/A.h5. + * If that target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * -# \p file_name is an absolute drive with relative pathname. + * For example, consider a \p file_name of \c /tmp/A.h5. If that + * target file does not exist, the new \p file_name after + * stripping will be \c tmp\A.h5. + * -# \p file_name is in UNC (Uniform Naming Convention) format with + * server name, share name, and pathname. For example, consider + * a \p file_name of \c /tmp/A.h5. If that target file does not + * exist, the new \p file_name after stripping will be \c A.h5. + * -# \p file_name is in Long UNC (Uniform Naming Convention) format + * with server name, share name, and pathname. For example, + * consider a \p file_name of \c /tmp/A.h5. If that target file + * does not exist, the new \p file_name after stripping will be + * \c A.h5. + * -# \p file_name is in Long UNC (Uniform Naming Convention) format + * with an absolute drive and an absolute pathname. For example, + * consider a \p file_name of \c /tmp/A.h5. If that target file + * does not exist, the new \p file_name after stripping will be + * \c A.h5. + * + * The library opens target file \p file_name with the file access + * property list that is set via H5Pset_elink_fapl() when the external + * link link_name is accessed. If no such property list is set, the + * library uses the file access property list associated with the file + * of \p link_loc_id to open the target file. + * + * If an application requires additional control over file access + * flags or the file access property list, see H5Pset_elink_cb(); this + * function enables the use of an external link callback function as + * described in H5L_elink_traverse_t(). + * + * \attention A file close degree property setting (H5Pset_fclose_degree()) in + * the external link file access property list or in the external + * link callback function will be ignored. A file opened by means of + * traversing an external link is always opened with the weak file + * close degree property setting, #H5F_CLOSE_WEAK . + * + * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_ud() + * + * \since 1.8.0 + */ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); diff --git a/src/H5MMpublic.h b/src/H5MMpublic.h index ebfb377..70ac644 100644 --- a/src/H5MMpublic.h +++ b/src/H5MMpublic.h @@ -29,8 +29,13 @@ #include "H5public.h" /* These typedefs are currently used for VL datatype allocation/freeing */ +//! <!-- [H5MM_allocate_t_snip] --> typedef void *(*H5MM_allocate_t)(size_t size, void *alloc_info); +//! <!-- [H5MM_allocate_t_snip] --> + +//! <!-- [H5MM_free_t_snip] --> typedef void (*H5MM_free_t)(void *mem, void *free_info); +//! <!-- [H5MM_free_t_snip] --> #ifdef __cplusplus extern "C" { diff --git a/src/H5Opublic.h b/src/H5Opublic.h index b0976a4..0931f9b 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -81,68 +81,95 @@ /* Public Typedefs */ /*******************/ -/* Types of objects in file */ +//! <!-- [H5O_type_t_snip] --> +/** + * Types of objects in file + */ typedef enum H5O_type_t { - H5O_TYPE_UNKNOWN = -1, /* Unknown object type */ - H5O_TYPE_GROUP, /* Object is a group */ - H5O_TYPE_DATASET, /* Object is a dataset */ - H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type */ - H5O_TYPE_NTYPES /* Number of different object types (must be last!) */ + H5O_TYPE_UNKNOWN = -1, /**< Unknown object type */ + H5O_TYPE_GROUP, /**< Object is a group */ + H5O_TYPE_DATASET, /**< Object is a dataset */ + H5O_TYPE_NAMED_DATATYPE, /**< Object is a named data type */ + H5O_TYPE_NTYPES /**< Number of different object types (must be last!) */ } H5O_type_t; +//! <!-- [H5O_type_t_snip] --> -/* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */ +//! <!-- [H5O_hdr_info_t_snip] --> +/** + * Information struct for object header metadata (for + * H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx()) + */ typedef struct H5O_hdr_info_t { - unsigned version; /* Version number of header format in file */ - unsigned nmesgs; /* Number of object header messages */ - unsigned nchunks; /* Number of object header chunks */ - unsigned flags; /* Object header status flags */ + unsigned version; /**< Version number of header format in file */ + unsigned nmesgs; /**< Number of object header messages */ + unsigned nchunks; /**< Number of object header chunks */ + unsigned flags; /**< Object header status flags */ struct { - hsize_t total; /* Total space for storing object header in file */ - hsize_t meta; /* Space within header for object header metadata information */ - hsize_t mesg; /* Space within header for actual message information */ - hsize_t free; /* Free space within object header */ + hsize_t total; /**< Total space for storing object header in file */ + hsize_t meta; /**< Space within header for object header metadata information */ + hsize_t mesg; /**< Space within header for actual message information */ + hsize_t free; /**< Free space within object header */ } space; struct { - uint64_t present; /* Flags to indicate presence of message type in header */ - uint64_t shared; /* Flags to indicate message type is shared in header */ + uint64_t present; /**< Flags to indicate presence of message type in header */ + uint64_t shared; /**< Flags to indicate message type is shared in header */ } mesg; } H5O_hdr_info_t; +//! <!-- [H5O_hdr_info_t_snip] --> -/* Information struct for object (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */ +//! <!-- [H5O_info_t_snip] --> +/** + * Data model information struct for objects + * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) + */ typedef struct H5O_info_t { - unsigned long fileno; /* File number that object is located in */ - haddr_t addr; /* Object address in file */ - H5O_type_t type; /* Basic object type (group, dataset, etc.) */ - unsigned rc; /* Reference count of object */ - time_t atime; /* Access time */ - time_t mtime; /* Modification time */ - time_t ctime; /* Change time */ - time_t btime; /* Birth time */ - hsize_t num_attrs; /* # of attributes attached to object */ - H5O_hdr_info_t hdr; /* Object header information */ + unsigned long fileno; /**< File number that object is located in */ + haddr_t addr; /**< Object address in file */ + H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ + unsigned rc; /**< Reference count of object */ + time_t atime; /**< Access time */ + time_t mtime; /**< Modification time */ + time_t ctime; /**< Change time */ + time_t btime; /**< Birth time */ + hsize_t num_attrs; /**< # of attributes attached to object */ + H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { - H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ - H5_ih_info_t attr; /* v2 B-tree & heap for attributes */ + H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ + H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ } meta_size; } H5O_info_t; +//! <!-- [H5O_info_t_snip] --> -/* Typedef for message creation indexes */ +/** + * Typedef for message creation indexes + */ typedef uint32_t H5O_msg_crt_idx_t; -/* Prototype for H5Ovisit/H5Ovisit_by_name() operator */ +//! <!-- [H5O_iterate_t_snip] --> +/** + * Prototype for H5Ovisit(), H5Ovisit_by_name() operator + */ typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data); +//! <!-- [H5O_iterate_t_snip] --> +//! <!-- [H5O_mcdt_search_ret_t_snip] --> typedef enum H5O_mcdt_search_ret_t { - H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */ - H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */ - H5O_MCDT_SEARCH_STOP /* Stop the search, but continue copying. The committed datatype will be copied but - not merged. */ + H5O_MCDT_SEARCH_ERROR = -1, /**< Abort H5Ocopy */ + H5O_MCDT_SEARCH_CONT, /**< Continue the global search of all committed datatypes in the destination file + */ + H5O_MCDT_SEARCH_STOP /**< Stop the search, but continue copying. The committed datatype will be copied + but not merged. */ } H5O_mcdt_search_ret_t; +//! <!-- [H5O_mcdt_search_ret_t_snip] --> -/* Callback to invoke when completing the search for a matching committed datatype from the committed dtype - * list */ +//! <!-- [H5O_mcdt_search_cb_t_snip] --> +/** + * Callback to invoke when completing the search for a matching committed + * datatype from the committed dtype list + */ typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data); +//! <!-- [H5O_mcdt_search_cb_t_snip] --> /********************/ /* Public Variables */ @@ -155,29 +182,1101 @@ typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data); extern "C" { #endif -H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); -H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); -H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, hid_t lapl_id); +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens an object in an HDF5 file by location identifier and path name. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Path to the object; relative to \p loc_id + * \lapl_id + * + * \return \hid_tv{object} + * + * \details H5Oopen() opens a group, dataset, or committed (named) datatype + * specified by a location, \p loc_id, and a path name, \p name, in an HDF5 file. + * + * This function opens the object in the same manner as H5Gopen(), H5Topen(), and H5Dopen(). + * However, H5Oopen() does not require the type of object to be known beforehand. + * This can be useful with user-defined links, for instance, when only a path may be known. + * + * H5Oopen() cannot be used to open a dataspace, attribute, property list, or file. + * + * Once an object of unknown type has been opened with H5Oopen(), + * the type of that object can be determined by means of an H5Iget_type() call. + * + * \p loc_id may be a file, group, dataset, named datatype, or attribute. + * If an attribute is specified for \p loc_id then the object where the + * attribute is attached will be accessed. + * + * \p name must be the path to that object relative to \p loc_id. + * + * \p lapl_id is the link access property list associated with the link pointing to + * the object. If default link access properties are appropriate, this can be + * passed in as #H5P_DEFAULT. + * + * When it is no longer needed, the opened object should be closed with + * H5Oclose(), H5Gclose(), H5Tclose(), or H5Dclose(). + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens an object using its address within an HDF5 file. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] addr Object's address in the file + * + * \return \hid_tv{object} + * + * \details H5Oopen_by_addr() opens a group, dataset, or committed (named) datatype using its + * address within an HDF5 file, \p addr. The resulting opened object is identical to + * an object opened with H5Oopen() and should be closed with H5Oclose() or an + * object-type-specific closing function (such as H5Gclose()) when no longer needed. + * + * \p loc_id is a location identifier in the file. + * + * 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>.) + * + * \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; + * H5Lget_info() returns the address in the \c address field of the #H5L_info_t \c struct. + * + * The address of the HDF5 file on a physical device has no effect on H5Oopen_by_addr(), + * nor does the use of any file driver. As stated above, the object address is its + * offset within the HDF5 file; HDF5’s file drivers will transparently map this to an + * address on a storage device. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * \warning This function is dangerous if called on an invalid address. The risk can be safely + * overcome by retrieving the object address with H5Gget_objinfo() or H5Lget_info() + * immediately before calling H5Oopen_by_addr(). The immediacy of the operation can be + * important; if time has elapsed and the object has been deleted from the file, + * the address will be invalid and file corruption can result. + * + * \version 1.8.4 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens the nth object in a group + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group, relative to \p loc_id, in which object is located + * \idx_type + * \order + * \param[in] n Object to open + * \lapl_id + * + * \return \hid_tv{object} + * + * \details H5Open_by_idx() opens the nth object in the group specified by \p loc_id + * and \p group_name. + * + * \p loc_id specifies a location identifier. + * \p group_name specifies the group relative to \p loc_id in which the object can be found. + * If \p loc_id fully specifies the group in which the object resides, + * \p group_name can be a dot (.). + * + * The specific object to be opened within the group is specified by the three parameters: + * \p idx_type, \p order and \p n. + * + * \p idx_type specifies the type of index by which objects are ordered. + * Valid index types include the following: + * + * \indexes + * + * \p order specifies the order in which the objects are to be referenced for the purposes + * of this function. Valid orders include the following: + * + * \orders + * + * Note that for #H5_ITER_NATIVE, rather than implying a particular order, + * it instructs the HDF5 library to iterate through the objects in the fastest + * available order, i.e., in a natural order. + * + * \p n specifies the position of the object within the index. Note that this count is + * zero-based; 0 (zero) indicates that the function will return the value of the first object; + * if \p n is 5, the function will return the value of the sixth object; etc. + * + * \p lapl_id specifies the link access property list to be used in accessing the object. + * + * An object opened with this function should be closed when it is no longer needed so that + * resource leaks will not develop. H5Oclose() can be used to close groups, datasets, + * or committed datatypes. + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, + hsize_t n, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Determines whether a link resolves to an actual object. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name The name of the link to check + * \lapl_id + * + * \return Returns a positive value if the object pointed to by + * the \p loc_id and \p name combination exists. + * \return Returns 0 if the object pointed to by + * the \p loc_id and \p name combination does not exist. + * \return Returns a negatvie value when the function fails. + * + * \details H5Oexists_by_name() allows an application to determine whether + * the link \p name in the group or file specified with \p loc_id + * resolves to an HDF5 object to open or if the link dangles. The + * link may be of any type, but hard links will always resolve + * to objects and do not need to be verified. + * + * Note that H5Oexists_by_name() verifies only that the target + * object exists. If \p name includes either a relative path or + * an absolute path to the target link, intermediate steps + * along the path must be verified before the existence of + * the target link can be safely checked. If the path is not + * verified and an intermediate element of the path does not + * exist, H5Oexists_by_name() will fail. The example in the next + * paragraph illustrates one step-by-step method for verifying + * the existence of a link with a relative or absolute path. + * + * \par Example + * Use the following steps to verify the existence of + * the link \c datasetD in the \c group group1/group2/softlink_to_group3/, + * where \c group1 is a member of the group specified by \c loc_id: + * + * \par + * - First use H5Lexists() to verify that a link named \c group1 exists. + * - If \c group1 exists, use H5Oexists_by_name() to verify that the + * link \c group1 resolves to an object. + * - If \c group1 exists, use H5Lexists() again, this time with name + * set to \c group1/group2, to verify that the link \c group2 exists + * in \c group1. + * - If the \c group2 link exists, use H5Oexists_by_name() to verify + * that \c group1/group2 resolves to an object. + * - If \c group2 exists, use H5Lexists() again, this time with name + * set to \c group1/group2/softlink_to_group3, to verify that the + * link \c softlink_to_group3 exists in \c group2. + * - If the \c softlink_to_group3 link exists, use H5Oexists_by_name() + * to verify that \c group1/group2/softlink_to_group3 resolves to + * an object. + * - If \c softlink_to_group3 exists, you can now safely use H5Lexists + * with name set to \c group1/group2/softlink_to_group3/datasetD to + * verify that the target link, \c datasetD, exists. + * - And finally, if the link \c datasetD exists, use H5Oexists_by_name + * to verify that \c group1/group2/softlink_to_group3/datasetD + * resolves to an object. + * + * \par + * If the link to be verified is specified with an absolute path, + * the same approach should be used, but starting with the first + * link in the file’s root group. For instance, if \c datasetD + * were in \c /group1/group2/softlink_to_group3, the first call to + * H5Lexists() would have name set to \c /group1. + * + * \par + * Note that this is an outline and does not include all necessary + * details. Depending on circumstances, for example, an application + * may need to verify the type of an object also. + * + * \warning \Bold{Failure Modes:} + * \warning If \p loc_id and \p name both exist but the combination does not + * resolve to an object, the function will return 0 (zero); + * the function does not fail in this case. + * \warning If either the location or the link specified by the \p loc_id + * and \p name combination does not exist, the function will fail, + * returning a negative value. + * \warning Note that verifying the existence of an object within an HDF5 + * file is a multistep process. An application can be certain the + * object does not exist only if H5Lexists() and H5Oexists_by_name() + * have been used to verify the existence of the links and groups + * in the hierarchy above that object. The example above, in the + * function description, provides a step-by-step description of + * that verification process. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.5 + * + */ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object specified by an identifier + * + * \fgdta_loc_obj_id{loc_id} + * \param[out] oinfo Buffer in which to return object information + * + * \return \herr_t + * + * \details H5Oget_info() specifies an object by its identifier, \p loc_id , and + * retrieves the metadata describing that object in \p oinfo , + * defined as a \c struct of type H5O_info_t : + * + * \snippet this H5O_info_t_snip + * + * Note the following about H5O_info_t : + * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) + * only \c ctime has been implemented. + * - The \c atime value is the last time the object was read or written. + * - The \c mtime value is the last time the raw data in the object was changed. + * - The \c ctime value is the last time the metadata for the object was changed. + * - The \c btime value is the time the object was created. + * - The fields nested in the \c meta_size field are for internal library use only. + * + * The #H5O_type_t \c enum indicates the object type and + * is defined in H5Opublic.h as follows: + * \snippet this H5O_type_t_snip + * + * Note that the object retrieved as indicated by \p loc_id + * refers only to the types specified by #H5O_type_t. + * + * An H5O_hdr_info_t \c struct holds object header metadata and is + * defined in H5Opublic.h as follows: + * \snippet this H5O_hdr_info_t_snip + * + * Valid values for the \c version field are \c H5O_VERSION_1 and \c H5O_VERSION_2. + * Version 2 of the object header is smaller and more efficient than version 1. + * + * Please be aware that the information held by H5O_hdr_info_t may only be useful to + * developers with extensive HDF5 experience. + * + * \note If you are iterating through a lot of different objects to + * retrieve information via the H5Oget_info() family of routines, + * you may see memory building up. This can be due to memory + * allocation for metadata such as object headers and messages + * when the iterated objects are put into the metadata cache. + * \note + * If the memory buildup is not desirable, you can configure a + * smaller cache via H5Fset_mdc_config() or set the file access + * property list via H5Pset_mdc_config(). A smaller sized cache + * will force metadata entries to be evicted from the cache, + * thus freeing the memory associated with the entries. + * + * \version 1.8.15 Added a note about the valid values for the \c version + * field in the H5O_hdr_info_t structure. + * \version 1.8.11 Fortran subroutine introduced in this release. + * \version 1.8.10 Added #H5O_type_t structure to the Description section. \n + * Separated H5O_hdr_info_t structure from #H5O_info_t in the + * Description section. \n + * Clarified the definition and implementation of the time fields. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by location and relative name + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of group, relative to \p loc_id + * \param[out] oinfo Buffer in which to return object information + * \lapl_id + * + * \return \herr_t + * + * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id + * and \p name, respectively, and retrieves the metadata describing that object + * in \p oinfo, an H5O_info1_t \c struct. + * + * The \c struct H5O_info_t is defined in H5Opublic.h and described + * in the H5Oget_info() function entry. + * + * The link access property list, \p lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \version 1.8.8 Fortran 2003 subroutine and \c h5o_info_t derived type introduced + * in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by an index position + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group in which object is located + * \idx_type + * \order + * \param[in] n Position within the index + * \param[out] oinfo Buffer in which to return object information + * \lapl_id + * + * \return \herr_t + * + * \details H5Oget_info_by_idx() retrieves the metadata describing an + * object in the \c struct \p oinfo, as specified by the location, + * \p loc_id, group name, \p group_name, the index by which objects + * in that group are tracked, \p idx_type, the order by which the + * index is to be traversed, \p order, and an object’s position + * \p n within that index. + * + * If \p loc_id fully specifies the group in which the object resides, + * \p group_name can be a dot (\c .). + * + * \p idx_type is of type #H5_index_t, defined in H5public.h as: + * \snippet H5public.h H5_index_t_snip + * + * \p order is of type #H5_iter_order_t defined in H5public.h as: + * \snippet H5public.h H5_iter_order_t_snip + * + * \p oinfo, in which the object information is returned, is a \c struct of + * type H5O_info_t . + * \snippet this H5O_info_t_snip + * + * The link access property list, \c lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo, hid_t lapl_id); +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Creates a hard link to an object in an HDF5 file + * + * \param[in] obj_id Object to be linked + * \param[in] new_loc_id Location identifier at which object is to be linked; + * may be a file, group, dataset, named datatype or attribute identifier. + * \param[in] new_name Name of link to be created, relative to \p new_loc_id. + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Olink() creates a new hard link to an object in an HDF5 file. + * \p new_loc_id and \p \p new_link_name specify the location and name of the + * new link while \p object_id identifies the object that the link + * points to. + * + * H5Olink() is designed for two purposes: + * - To create the first hard link to an object that has just + * been created with H5Dcreate_anon(), H5Gcreate_anon(), or + * H5Tcommit_anon(). + * - To add additional structure to an existing + * file so that, for example, an object can be shared among + * multiple groups. + * + * \p lcpl and \p lapl are the link creation and access property lists + * associated with the new link. + * + * \par Example: + * To create a new link to an object while simultaneously creating + * missing intermediate groups: Suppose that an application must + * create the group C with the path /A/B01/C but may not know + * at run time whether the groups A and B01 exist. The following + * code ensures that those groups are created if they are missing: + * \par + * \code + * + * // Creates a link creation property list (LCPL). + * hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE); + * + * // Sets "create missing intermediate groups" property in that LCPL. + * int status = H5Pset_create_intermediate_group(lcpl_id, TRUE); + * + * // Creates a group without linking it into the file structure. + * hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT); + * + * // Links group into file structure. + * status = H5Olink(gid, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT); + * + * \endcode + * + * \par + * Note that unless the object is intended to be temporary, + * the H5O_LINK call is mandatory if an object created with one + * of the H5*_CREATE_ANON functions (or with H5T_COMMIT_ANON) + * is to be retained in the file; without an H5O_LINK call, + * the object will not be linked into the HDF5 file structure + * and will be deleted when the file is closed. + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Increments an object reference count + * + * \fgdta_loc_obj_id{object_id} + * + * \return \herr_t + * + * \details H5Oincr_refcount() increments the hard link reference count for an object. + * It should be used any time a user-defined link that references + * an object by address is added. When the link is deleted, + * H5Odecr_refcount() should be used. + * + * 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> + * for a more complete discussion of reference counts. + * + * If a user application needs to determine an object’s reference + * count, an H5Oget_info() call is required; the reference count + * is returned in the \c rc field of the #H5O_info_t \c struct. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oincr_refcount(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Decrements an object reference count + * + * \fgdta_loc_obj_id{object_id} + * + * \return \herr_t + * + * \details H5Odecr_refcount() decrements the hard link reference count for an object. + * It should be used any time a user-defined link that references + * an object by address is deleted. In general, H5Oincr_refcount() will have + * been used previously, when the link was created. + * + * 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> + * for a more complete discussion of reference counts. + * + * If a user application needs to determine an object’s reference + * count, an H5Oget_info() call is required; the reference count + * is returned in the \c rc field of the #H5O_info_t \c struct. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Odecr_refcount(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Copies an object in an HDF5 file + * + * \param[in] src_loc_id Object identifier indicating the location of the + * source object to be copied + * \param[in] src_name Name of the source object to be copied + * \param[in] dst_loc_id Location identifier specifying the destination + * \param[in] dst_name Name to be assigned to the new copy + * \param[in] ocpypl_id Object copy property list + * \lcpl_id + * + * \return \herr_t + * + * \details H5Ocopy() copies the group, dataset or committed datatype + * specified by \p src_name from the file or group specified by + * \p src_loc_id to the destination location \p dst_loc_id. + * + * The destination location, as specified in dst_loc_id, may + * be a group in the current file or a location in a different + * file. If dst_loc_id is a file identifier, the copy will be + * placed in that file’s root group. + * + * The copy will be created with the path specified in \p dst_name, + * which must not pre-exist in the destination location. If + * \p dst_name already exists at the location \p dst_loc_id, + * H5Ocopy() will fail. If \p dst_name is an absolute path, + * the copy will be created relative to the file’s root group. + * + * The copy of the object is created with the property lists + * specified by \p ocpypl_id and \p lcpl_id. #H5P_DEFAULT can be passed + * in for these property lists. The default behavior: + * + * - of the link creation property list is to NOT create + * intermediate groups. + * - of the flags specified by the object creation property list + * is described in H5Pset_copy_object(). + * + * These property lists or flags can be modified to govern the + * behavior of H5Ocopy() as follows: + * + * - A flag controlling the creation of intermediate groups that + * may not yet exist is set in the link creation property list + * \p lcpl_id with H5Pset_create_intermediate_group(). + * + * - Copying of committed datatypes can be tuned through the use + * of H5Pset_copy_object(), H5Padd_merge_committed_dtype_path(), + * H5Pset_mcdt_search_cb(), and related functions. + * + * - Flags controlling other aspects of object copying are set in the + * object copy property list \p ocpypl_id with H5Pset_copy_object(). + * + * H5Ocopy() will always try to make a copy of the object specified + * in \p src_name. + * + * - If the object specified by \p src_name is a group containing a + * soft or external link, the default is that the new copy will + * contain a soft or external link with the same value as the + * original. See H5Pset_copy_object() for optional settings. + * + * - If the path specified in \p src_name is or contains a soft link + * or an external link, H5Ocopy() will copy the target object. + * Use H5Lcopy() if the intent is to create a new soft or external + * link with the same value as the original link. + * + * H5Ocopy() can be used to copy an object in an HDF5 file. If + * an object has been changed since it was opened, it should be + * written back to the file before using H5Ocopy(). The object + * can be written back either by closing the object (H5Gclose(), + * H5Oclose(), H5Dclose(), or H5Tclose()) or by flushing + * the HDF5 file (H5Fflush()). + * + * \par See Also: + * - Functions to modify the behavior of H5Ocopy(): + * - H5Padd_merge_committed_dtype_path() + * - H5Pset_copy_object() + * - H5Pset_create_intermediate_group() + * - H5Pset_mcdt_search_cb() + * - Copying Committed Datatypes with #H5Ocopy - A comprehensive + * discussion of copying committed datatypes (PDF) in + * Advanced Topics in HDF5 + * + * \version 1.8.9 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Sets comment for specified object + * + * \fgdta_loc_obj_id{obj_id} + * \param[in] comment The new comment + * + * \return \herr_t + * + * \details H5Oset_comment() sets the comment for the specified object + * to the contents of \p comment. Any previously existing comment + * is overwritten. + * + * The target object is specified by an identifier, \p obj_id. + * If \p comment is the empty string or a null pointer, any existing + * comment message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object + * header. Datasets, groups, and committed (named) datatypes have + * object headers. Symbolic links do not have object headers. + * + * If a comment is being added to an object attribute, this comment + * will be attached to the object to which the attribute belongs + * and not to the attribute itself. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Sets comment for specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of the object whose comment is to be set or reset + * \param[in] comment The new comment + * \lapl_id + * + * \return \herr_t + * + * \details H5Oset_comment_by_name() sets the comment for the specified object + * to the contents of \p comment. Any previously existing comment + * is overwritten. + * + * The target object is specified by \p loc_id and \p name. + * \p loc_id can specify any object in the file. + * \p name can be one of the following: + * + * - The name of the object specified as a path relative to \p loc_id + * - An absolute name of the object, starting from \c /, the file’s root group + * - A dot (\c .), if \p loc_id fully specifies the object + * + * If \p comment is the empty string or a null pointer, any existing + * comment message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object + * header. Datasets, groups, and committed (named) datatypes have + * object headers. Symbolic links do not have object headers. + * + * If a comment is being added to an object attribute, this comment + * will be attached to the object to which the attribute belongs + * and not to the attribute itself. + * + * \p lapl_id contains a link access property list identifier. A + * link access property list can come into play when traversing + * links to access an object. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name, const char *comment, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves comment for specified object + * + * \fgdta_loc_obj_id{obj_id} + * \param[out] comment The comment + * \param[in] bufsize Anticipated required size of the comment buffer + * + * \return Upon success, returns the number of characters in the + * comment, not including the \c NULL terminator, or zero (\c 0) if + * the object has no comment. The value returned may be larger + * than \p bufsize. Otherwise returns a negative value. + * + * \details H5Oget_comment() retrieves the comment for the specified object in + * the buffer \p comment. + * + * The target object is specified by an identifier, \p object_id. + * + * The size in bytes of the buffer \p comment, including the \c NULL + * terminator, is specified in \p bufsize. If \p bufsize is unknown, + * a preliminary H5Oget_comment() call with the pointer \p comment + * set to \c NULL will return the size of the comment <em>without</em> + * the \c NULL terminator. + * + * If \p bufsize is set to a smaller value than described above, + * only \p bufsize bytes of the comment, without a \c NULL terminator, + * are returned in \p comment. + * + * If an object does not have a comment, the empty string is + * returned in \p comment. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves comment for specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of the object whose comment is to be retrieved + * \param[out] comment The comment + * \param[in] bufsize Anticipated required size of the \p comment buffer + * \lapl_id + * + * \return Upon success, returns the number of characters in the comment, + * not including the \c NULL terminator, or zero (\c 0) if the object + * has no comment. The value returned may be larger than \c bufsize. + * Otherwise returns a negative value. + * + * \details H5Oget_comment_by_name() retrieves the comment for an object + * in the buffer \p comment. + * + * The target object is specified by \p loc_id and \p name. + * \p loc_id can specify any object in the file. + * \p name can be one of the following: + * + * - The name of the object relative to \p loc_id + * - An absolute name of the object, starting from \c /, the file’s root group + * - A dot (\c .), if \p loc_id fully specifies the object + * + * The size in bytes of the comment, including the \c NULL terminator, + * is specified in \p bufsize. If \p bufsize is unknown, a preliminary + * H5Oget_comment_by_name() call with the pointer \p comment set + * to \c NULL will return the size of the comment <em>without</em> + * the \c NULL terminator. + * + * If \p bufsize is set to a smaller value than described above, + * only \p bufsize bytes of the comment, without a \c NULL terminator, + * are returned in \p comment. + * + * If an object does not have a comment, the empty string is + * returned in \p comment. + * + * \p lapl_id contains a link access property list identifier. A + * link access property list can come into play when traversing + * links to access an object. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id); -H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, - void *op_data); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects accessible from a specified object + * + * \fgdta_loc_obj_id{obj_id} + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \details H5Ovisit() is a recursive iteration function to visit the + * object \p obj_id and, if \p obj_id is a group, all objects in + * and below it in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all + * of those objects or a dynamically selected subset. For + * non-recursive iteration across the members of a group, + * see H5Literate(). + * + * If \p obj_id is a group identifier, that group serves as the + * root of a recursive iteration. If \p obj_id is a file identifier, + * that file’s root group serves as the root of the recursive + * iteration. If \p obj_id is an attribute identifier, + * then the object where the attribute is attached will be iterated. + * If \p obj_id is any other type of object, such as a dataset or + * named datatype, there is no iteration. + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * a group have not been indexed by the index type, they will + * first be sorted by that index then the iteration will begin; + * if the links have been so indexed, the sorting step will be + * unnecessary, so the iteration may begin more quickly. Valid + * values include the following: + * + * \indexes + * + * Note that the index type passed in \p idx_type is a + * <em>best effort</em> setting. If the application passes in + * a value indicating iteration in creation order and a group is + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The prototype of the callback function op is as follows (as + * defined in the source code file H5Opublic.h): + * + * \snippet this H5O_iterate_t_snip + * + * The parameters of this callback function have the following values + * or meanings: + * <table> + * <tr> + * <td>\c obj</td> + * <td>Object that serves as root of the iteration; + * same value as the H5Ovisit() \p obj_id parameter</td> + * </tr> + * <tr> + * <td>\c name</td> + * <td>Name of object, relative to \c obj, being examined at + * current step of the iteration</td> + * </tr> + * <tr> + * <td>\c info</td> + * <td>H5O_info1_t \c struct containing information + * regarding that object</td> + * </tr> + * <tr> + * <td>\c op_data</td> + * <td>User-defined pointer to data required by the application in + * processing the object</td> + * </tr> + * </table> + * + * The H5O_info_t \c struct is defined in H5Opublic.h: + * \snippet this H5O_info_t_snip + * + * The return values from an operator are: + * - Zero causes the visit iterator to continue, returning zero when all + * group members have been processed. + * - A positive value causes the visit iterator to immediately return that + * positive value, indicating short-circuit success. + * - A negative value causes the visit iterator to immediately return that + * value, indicating failure. + * + * The H5Ovisit() \p op_data parameter is a user-defined pointer to the data + * required to process objects in the course of the iteration. This pointer + * is passed back to each step of the iteration in the callback + * function’s \p op_data parameter. + * + * H5Lvisit() and H5Ovisit() are companion functions: one for + * examining and operating on links; the other for examining + * and operating on the objects that those links point to. Both + * functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. These functions assume + * that the membership of the group being iterated over remains + * unchanged through the iteration; if any of the links in the + * group change during the iteration, the resulting behavior + * is undefined. + * + * \note \Bold{Programming Note for C++ Developers Using C Functions:} + * \note If a C routine that takes a function pointer as an argument is + * called from within C++ code, the C routine should be returned + * from normally. + * + * \note Examples of this kind of routine include callbacks such as + * H5Pset_elink_cb() and H5Pset_type_conv_cb() and + * functions such as H5Tconvert() and H5Ewalk2(). + * + * \note Exiting the routine in its normal fashion allows the HDF5 + * C library to clean up its work properly. In other words, if + * the C++ application jumps out of the routine back to the C++ + * “catch” statement, the library is not given the opportunity + * to close any temporary data structures that were set up when + * the routine was called. The C++ application should save some + * state as the routine is started so that any problem that occurs + * might be diagnosed. + * + * \version 1.8.8 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, + void *op_data); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects starting from a specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] obj_name Name of the object, generally relative to + * \p loc_id, that will serve as root of the iteration + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \lapl_id + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \details H5Ovisit_by_name() is a recursive iteration function to visit + * the object specified by the \p loc_id / \p obj_name parameter + * pair and, if that object is a group, all objects in and below it + * in an HDF5 file, thus providing a mechanism for an application to + * perform a common set of operations across all of those objects or + * a dynamically selected subset. For non-recursive iteration across + * the members of a group, see H5Literate(). + * + * The object serving as the root of the iteration is specified + * by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies + * a file or an object in a file; if \p loc_id is an attribute identifier, + * the object where the attribute is attached will be used. + * \p obj_name specifies either an object in the file (with an absolute + * name based in the file’s root group) or an object name relative + * to \p loc_id. If \p loc_id fully specifies the object that is to serve + * as the root of the iteration, \p obj_name should be '\c .' (a dot). + * (Note that when \p loc_id fully specifies the object that is to serve + * as the root of the iteration, the user may wish to consider + * using H5Ovisit() instead of H5Ovisit_by_name().) + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * a group have not been indexed by the index type, they will + * first be sorted by that index then the iteration will begin; + * if the links have been so indexed, the sorting step will be + * unnecessary, so the iteration may begin more quickly. Valid + * values include the following: + * + * \indexes + * + * Note that the index type passed in \p idx_type is a + * <em>best effort</em> setting. If the application passes in a + * value indicating iteration in creation order and a group is + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The \p op callback function and the effect of the callback + * function’s return value on the application are described + * in H5Ovisit(). + * + * The H5O_info_t \c struct is defined in H5Opublic.h + * and described in the H5Oget_info() function entry. + * + * The H5Ovisit_by_name() \p op_data parameter is a user-defined + * pointer to the data required to process objects in the course + * of the iteration. This pointer is passed back to each step of + * the iteration in the callback function’s \p op_data parameter. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can + * be passed in as #H5P_DEFAULT. An example of a situation that + * requires a non-default link access property list is when + * the link is an external link; an external link may require + * that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). + * + * H5Lvisit_by_name() and H5Ovisit_by_name() are companion + * functions: one for examining and operating on links; the other + * for examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. + * + * \note \Bold{Programming Note for C++ Developers Using C Functions:} + * \note If a C routine that takes a function pointer as an argument is + * called from within C++ code, the C routine should be returned + * from normally. + * + * \note Examples of this kind of routine include callbacks such as + * H5Pset_elink_cb() and H5Pset_type_conv_cb() and + * functions such as H5Tconvert() and H5Ewalk2(). + * + * \note Exiting the routine in its normal fashion allows the HDF5 + * C library to clean up its work properly. In other words, if + * the C++ application jumps out of the routine back to the C++ + * “catch” statement, the library is not given the opportunity + * to close any temporary data structures that were set up when + * the routine was called. The C++ application should save some + * state as the routine is started so that any problem that occurs + * might be diagnosed. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ovisit_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Closes an object in an HDF5 file + * + * \obj_id{object_id} + * + * \return \herr_t + * + * \details H5Oclose() closes the group, dataset, or named datatype specified by + * object_id. + * + * This function is the companion to H5Oopen(), and has the same + * effect as calling H5Gclose(), H5Dclose(), or H5Tclose(). + * + * H5Oclose() is not used to close a dataspace, attribute, property + * list, or file. + * + * \version 1.8.8 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oclose(hid_t object_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -190,13 +1289,18 @@ H5_DLL herr_t H5Oclose(hid_t object_id); /* Typedefs */ -/* A struct that's part of the H5G_stat_t structure (deprecated) */ +//! <!-- [H5O_stat_t_snip] --> +/** + * A struct that's part of the \ref H5G_stat_t structure + * \deprecated + */ typedef struct H5O_stat_t { - hsize_t size; /* Total size of object header in file */ - hsize_t free; /* Free space within object header */ - unsigned nmesgs; /* Number of object header messages */ - unsigned nchunks; /* Number of object header chunks */ + hsize_t size; /**< Total size of object header in file */ + hsize_t free; /**< Free space within object header */ + unsigned nmesgs; /**< Number of object header messages */ + unsigned nchunks; /**< Number of object header chunks */ } H5O_stat_t; +//! <!-- [H5O_stat_t_snip] --> /* Function prototypes */ #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h index 549f34d..6bf46bf 100644 --- a/src/H5PLpublic.h +++ b/src/H5PLpublic.h @@ -24,12 +24,16 @@ /* Public Typedefs */ /*******************/ -/* Plugin type used by the plugin library */ +//! <!-- [H5PL_type_t_snip] --> +/** + * Plugin type (bit-position) used by the plugin library + */ typedef enum H5PL_type_t { - H5PL_TYPE_ERROR = -1, /* Error */ - H5PL_TYPE_FILTER = 0, /* Filter */ - H5PL_TYPE_NONE = 1 /* This must be last! */ + H5PL_TYPE_ERROR = -1, /**< Error */ + H5PL_TYPE_FILTER = 0, /**< Filter */ + H5PL_TYPE_NONE = 1 /**< This must be last! */ } H5PL_type_t; +//! <!-- [H5PL_type_t_snip] --> /* Common dynamic plugin type flags used by the set/get_loading_state functions */ #define H5PL_FILTER_PLUGIN 0x0001 @@ -40,15 +44,175 @@ extern "C" { #endif /* plugin state */ -H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_type); -H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_type /*out*/); -H5_DLL herr_t H5PLappend(const char *plugin_path); -H5_DLL herr_t H5PLprepend(const char *plugin_path); -H5_DLL herr_t H5PLreplace(const char *plugin_path, unsigned int index); -H5_DLL herr_t H5PLinsert(const char *plugin_path, unsigned int index); -H5_DLL herr_t H5PLremove(unsigned int index); -H5_DLL ssize_t H5PLget(unsigned int index, char *pathname /*out*/, size_t size); -H5_DLL herr_t H5PLsize(unsigned int *listsize /*out*/); +/** + * \ingroup H5PL + * \brief Controls the loadability of dynamic plugin types + * + * \param[in] plugin_control_mask The list of dynamic plugin types to enable or disable.\n + * A plugin bit set to 0 (zero) prevents use of that dynamic plugin.\n + * A plugin bit set to 1 (one) enables use of that dynamic plugin.\n + * Setting \p plugin_control_mask to a negative value enables all dynamic + * plugin types.\n + * Setting \p plugin_control_mask to 0 (zero) disables all dynamic plugin\n + * types. + * \return \herr_t + * + * \details H5PLset_loading_state() uses one argument to enable or disable individual plugin types. + * + * \details The \p plugin_control_mask parameter is an encoded integer in which each bit controls a specific + * plugin type. Bit positions allocated to date are specified in \ref H5PL_type_t as follows: + * \snippet this H5PL_type_t_snip + * + * A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit + * position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type. + * + * All dynamic plugin types can be enabled by setting \p plugin_control_mask to a negative value. A + * value of 0 (zero) will disable all dynamic plugin types. + * + * The loading of external dynamic plugins can be controlled during runtime with an environment + * variable, \c HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the \c HDF5_PLUGIN_PRELOAD + * environment variable every time it is called. If the environment variable is set to the special + * \c :: string, all dynamic plugins are disabled. + * + * \warning The environment variable \c HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at + * runtime. If it is set to disable all plugin types, then it will disable them for \Emph{all} + * running programs that access the same variable instance. + * + * \since 1.8.15 + * + */ +H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask); +/** + * \ingroup H5PL + * \brief Queries the loadability of dynamic plugin types + * + * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n + * A plugin bit set to 0 (zero) indicates that that the dynamic plugin type is + * disabled.\n + * A plugin bit set to 1 (one) indicates that that the dynamic plugin type is + * enabled.\n + * If the value of \p plugin_control_mask is negative, all dynamic plugin + * types are enabled.\n + * If the value of \p plugin_control_mask is 0 (zero), all dynamic plugins + * are disabled. + * \return \herr_t + * + * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugins + * (e.g.: filters, VOL drivers) will be loaded by the HDF5 library. + * + * Bit positions allocated to date are specified in \ref H5PL_type_t as follows: + * \snippet this H5PL_type_t_snip + * + * \since 1.8.15 + * + */ +H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/); +/** + * \ingroup H5PL + * \brief Inserts a plugin path at the end of the plugin search path list + * + * \param[in] search_path A plugin path + * \return \herr_t + * + * \details H5PLappend() inserts a plugin path at the end of the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLappend(const char *search_path); +/** + * \ingroup H5PL + * \brief Inserts a plugin path at the beginning of the plugin search path list + * + * \param[in] search_path A plugin path + * \return \herr_t + * + * \details H5PLprepend() inserts a plugin path at the end of the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLprepend(const char *search_path); +/** + * \ingroup H5PL + * \brief Replaces the path at the specified index in the plugin search path list + * + * \param[in] search_path A plugin path + * \param[in] index Index + * \return \herr_t + * + * \details H5PLreplace() replaces a plugin path at the specified index in the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLreplace(const char *search_path, unsigned int index); +/** + * \ingroup H5PL + * \brief Inserts a path at the specified index in the plugin search path list + * + * \param[in] search_path A plugin path + * \param[in] index Index + * \return \herr_t + * + * \details H5PLinsert() inserts a plugin path at the specified index in the plugin search path list, + * moving other paths after \p index. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLinsert(const char *search_path, unsigned int index); +/** + * \ingroup H5PL + * \brief Removes a plugin path at a specified index from the plugin search path list + * + * \param[in] index Index + * \return \herr_t + * + * \details H5PLremove() removes a plugin path at the specified \p index and compacts the plugin search path + * list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLremove(unsigned int index); +/** + * \ingroup H5PL + * \brief Queries the plugin search path list at the specified index + * + * \param[in] index Index + * \param[out] path_buf Pathname + * \param[in] buf_size Size of \p path_buf + * \return Returns the length of the path, a non-negative value, if successful; otherwise returns a negative + * value. + * + * \details H5PLget() queries the plugin path at a specified index. If \p path_buf is non-NULL then it writes + * up to \p buf_size bytes into that buffer and always returns the length of the path name. + * + * If \p path_buf is NULL, this function will simply return the number of characters required to + * store the path name, ignoring \p path_buf and \p buf_size. + * + * If an error occurs then the buffer pointed to by \p path_buf (NULL or non-NULL) is unchanged and + * the function returns a negative value. If a zero is returned for the name's length, then there is + * no path name associated with the index. and the \p path_buf buffer will be unchanged. + * + * \since 1.10.1 + * + */ +H5_DLL ssize_t H5PLget(unsigned int index, char *path_buf /*out*/, size_t buf_size); +/** + * \ingroup H5PL + * \brief Retrieves the number of stored plugin paths + * + * \param[out] num_paths Current length of the plugin search path list + * \return \herr_t + * + * \details H5PLsize() retrieves the number of paths stored in the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLsize(unsigned int *num_paths /*out*/); #ifdef __cplusplus } diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 01986ea..2cac8b8 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -101,66 +101,136 @@ extern "C" { /*******************/ /* Define property list class callback function pointer types */ +//! <!-- [H5P_cls_create_func_t_snip] --> typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); +//! <!-- [H5P_cls_create_func_t_snip] --> + +//! <!-- [H5P_cls_copy_func_t_snip] --> typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); +//! <!-- [H5P_cls_copy_func_t_snip] --> + +//! <!-- [H5P_cls_close_func_t_snip] --> typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); +//! <!-- [H5P_cls_close_func_t_snip] --> /* Define property list callback function pointer types */ +//! <!-- [H5P_prp_cb1_t_snip] --> +/** + * \brief Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1() + * + * \param[in] name The name of the property + * \param[in] size The size of the property in bytes + * \param[in,out] value The value for the property + * \return \herr_t + * + * \details The H5P_prp_cb1_t() describes the parameters used by the + * property create,copy and close callback functions. + */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); +//! <!-- [H5P_prp_cb1_t_snip] --> + +//! <!-- [H5P_prp_cb2_t_snip] --> +/** + * \brief Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1() + * + * \plist_id{prop_id} + * \param[in] name The name of the property + * \param[in] size The size of the property in bytes + * \param[in] value The value for the property + * \return \herr_t + * + * \details The H5P_prp_cb2_t() describes the parameters used by the + * property set ,copy and delete callback functions. + */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); +//! <!-- [H5P_prp_cb2_t_snip] --> + typedef H5P_prp_cb1_t H5P_prp_create_func_t; typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; typedef H5P_prp_cb2_t H5P_prp_delete_func_t; typedef H5P_prp_cb1_t H5P_prp_copy_func_t; + +//! <!-- [H5P_prp_compare_func_t_snip] --> typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); +//! <!-- [H5P_prp_compare_func_t_snip] --> + typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ +//! <!-- [H5P_iterate_t_snip] --> typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); +//! <!-- [H5P_iterate_t_snip] --> -/* Actual IO mode property */ +//! <!--[H5D_mpio_actual_chunk_opt_mode_t_snip] --> +/** + * Actual IO mode property + * + * \details The default value, #H5D_MPIO_NO_CHUNK_OPTIMIZATION, is used for all + * I/O operations that do not use chunk optimizations, including + * non-collective I/O and contiguous collective I/O. + */ typedef enum H5D_mpio_actual_chunk_opt_mode_t { - /* The default value, H5D_MPIO_NO_CHUNK_OPTIMIZATION, is used for all I/O - * operations that do not use chunk optimizations, including non-collective - * I/O and contiguous collective I/O. - */ H5D_MPIO_NO_CHUNK_OPTIMIZATION = 0, + /**< No chunk optimization was performed. Either no collective I/O was + attempted or the dataset wasn't chunked. */ H5D_MPIO_LINK_CHUNK, + /**< Collective I/O is performed on all chunks simultaneously. */ H5D_MPIO_MULTI_CHUNK + /**< Each chunk was individually assigned collective or independent I/O based + on what fraction of processes access the chunk. If the fraction is greater + than the multi chunk ratio threshold, collective I/O is performed on that + chunk. The multi chunk ratio threshold can be set using + H5Pset_dxpl_mpio_chunk_opt_ratio(). The default value is 60%. */ } H5D_mpio_actual_chunk_opt_mode_t; +//! <!--[H5D_mpio_actual_chunk_opt_mode_t_snip] --> +//! <!-- [H5D_mpio_actual_io_mode_t_snip] --> +/** + * The following values are conveniently defined as a bit field so that + * we can switch from the default to independent or collective and then to + * mixed without having to check the original value. + */ typedef enum H5D_mpio_actual_io_mode_t { - /* The following four values are conveniently defined as a bit field so that - * we can switch from the default to independent or collective and then to - * mixed without having to check the original value. - * - * NO_COLLECTIVE means that either collective I/O wasn't requested or that - * no I/O took place. - * - * CHUNK_INDEPENDENT means that collective I/O was requested, but the - * chunk optimization scheme chose independent I/O for each chunk. - */ - H5D_MPIO_NO_COLLECTIVE = 0x0, + H5D_MPIO_NO_COLLECTIVE = 0x0, + /**< No collective I/O was performed. Collective I/O was not requested or + collective I/O isn't possible on this dataset */ H5D_MPIO_CHUNK_INDEPENDENT = 0x1, - H5D_MPIO_CHUNK_COLLECTIVE = 0x2, - H5D_MPIO_CHUNK_MIXED = 0x1 | 0x2, - - /* The contiguous case is separate from the bit field. */ + /**< HDF5 performed one the chunk collective optimization schemes and each + chunk was accessed independently */ + H5D_MPIO_CHUNK_COLLECTIVE = 0x2, + /**< HDF5 performed one the chunk collective optimization schemes and each + chunk was accessed collectively */ + H5D_MPIO_CHUNK_MIXED = 0x1 | 0x2, + /**< HDF5 performed one the chunk collective optimization schemes and some + chunks were accessed independently, some collectively. */ + /** \internal The contiguous case is separate from the bit field. */ H5D_MPIO_CONTIGUOUS_COLLECTIVE = 0x4 + /**< Collective I/O was performed on a contiguous dataset */ } H5D_mpio_actual_io_mode_t; +//! <!-- [H5D_mpio_actual_io_mode_t_snip] --> -/* Broken collective IO property */ +//! <!-- [H5D_mpio_no_collective_cause_t_snip] --> +/** + * Broken collective IO property + */ typedef enum H5D_mpio_no_collective_cause_t { - H5D_MPIO_COLLECTIVE = 0x00, - H5D_MPIO_SET_INDEPENDENT = 0x01, - H5D_MPIO_DATATYPE_CONVERSION = 0x02, - H5D_MPIO_DATA_TRANSFORMS = 0x04, - H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, + H5D_MPIO_COLLECTIVE = 0x00, + /**< Collective I/O was performed successfully */ + H5D_MPIO_SET_INDEPENDENT = 0x01, + /**< Collective I/O was not performed because independent I/O was requested */ + H5D_MPIO_DATATYPE_CONVERSION = 0x02, + /**< Collective I/O was not performed because datatype conversions were required */ + H5D_MPIO_DATA_TRANSFORMS = 0x04, + /**< Collective I/O was not performed because data transforms needed to be applied */ + H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, + /**< \todo FIXME! */ + H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, + /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, H5D_MPIO_FILTERS = 0x40 } H5D_mpio_no_collective_cause_t; +//! <!-- [H5D_mpio_no_collective_cause_t_snip] --> /********************/ /* Public Variables */ @@ -208,214 +278,7223 @@ H5_DLLVAR hid_t H5P_LST_LINK_ACCESS_ID_g; /*********************/ /* Generic property list routines */ -H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create, - void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data, - H5P_cls_close_func_t cls_close, void *close_data); -H5_DLL char * H5Pget_class_name(hid_t pclass_id); -H5_DLL hid_t H5Pcreate(hid_t cls_id); -H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, - H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, - H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, - H5P_prp_copy_func_t prp_copy, H5P_prp_compare_func_t prp_cmp, - H5P_prp_close_func_t prp_close); -H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *value, - H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, - H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, - H5P_prp_compare_func_t prp_cmp, H5P_prp_close_func_t prp_close); -H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, void *value); + +/** + * \ingroup GPLO + * + * \brief Terminates access to a property list + * + * \plist_id + * + * \return \herr_t + * + * \details H5Pclose() terminates access to a property list. All property + * lists should be closed when the application is finished + * accessing them. This frees resources used by the property + * list. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pclose(hid_t plist_id); +/** + * \ingroup GPLOA + * + * \brief Closes an existing property list class + * + * \plistcls_id{plist_id} + * + * \return \herr_t + * + * \details H5Pclose_class() removes a property list class from the library. + * Existing property lists of this class will continue to exist, + * but new ones are not able to be created. + * + * \since 1.4.0 + * + */ +H5_DLL herr_t H5Pclose_class(hid_t plist_id); +/** + * \ingroup GPLO + * + * \brief Copies an existing property list to create a new property list + * + * \plist_id + * + * \return \hid_t{property list} + * + * \details H5Pcopy() copies an existing property list to create a new + * property list. The new property list has the same properties + * and values as the original property list. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Pcopy(hid_t plist_id); +/** + * \ingroup GPLOA + * + * \brief Copies a property from one list or class to another + * + * \param[in] dst_id Identifier of the destination property list or class + * \param[in] src_id Identifier of the source property list or class + * \param[in] name Name of the property to copy + * + * \return \herr_t + * + * \details H5Pcopy_prop() copies a property from one property list or + * class to another. + * + * If a property is copied from one class to another, all the + * property information will be first deleted from the destination + * class and then the property information will be copied from the + * source class into the destination class. + * + * If a property is copied from one list to another, the property + * will be first deleted from the destination list (generating a + * call to the close callback for the property, if one exists) + * and then the property is copied from the source list to the + * destination list (generating a call to the copy callback for + * the property, if one exists). + * + * If the property does not exist in the class or list, this + * call is equivalent to calling H5Pregister() or H5Pinsert() (for + * a class or list, as appropriate) and the create callback will + * be called in the case of the property being copied into a list + * (if such a callback exists for the property). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); +/** + * \ingroup GPLO + * + * \brief Creates a new property list as an instance of a property list class + * + * \plistcls_id{cls_id} + * + * \return \hid_t{property list} + * + * \details H5Pcreate() creates a new property list as an instance of + * some property list class. The new property list is initialized + * with default values for the specified class. The classes are as + * follows: + * + * <table> + * <tr> + * <th>Class Identifier</th> + * <th>Class Name</th> + * <th>Comments</th> + * </tr> + * <tr> + * <td>#H5P_ATTRIBUTE_CREATE</td> + * <td>attribute create</td> + * <td>Properties for attribute creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_ACCESS</td> + * <td>dataset access</td> + * <td>Properties for dataset access</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_CREATE</td> + * <td>dataset create</td> + * <td>Properties for dataset creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_XFER</td> + * <td>data transfer</td> + * <td>Properties for raw data transfer</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_ACCESS</td> + * <td>datatype access</td> + * <td>Properties for datatype access</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_CREATE</td> + * <td>datatype create</td> + * <td>Properties for datatype creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_ACCESS</td> + * <td>file access</td> + * <td>Properties for file access</td> + * </tr> + * <tr> + * <td>#H5P_FILE_CREATE</td> + * <td>file create</td> + * <td>Properties for file creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_MOUNT</td> + * <td>file mount</td> + * <td>Properties for file mounting</td> + * </tr> + * <tr valign="top"> + * <td>#H5P_GROUP_ACCESS</td> + * <td>group access</td> + * <td>Properties for group access</td> + * </tr> + * <tr> + * <td>#H5P_GROUP_CREATE</td> + * <td>group create</td> + * <td>Properties for group creation</td> + * </tr> + * <tr> + * <td>#H5P_LINK_ACCESS</td> + * <td>link access</td> + * <td>Properties governing link traversal when accessing objects</td> + * </tr> + * <tr> + * <td>#H5P_LINK_CREATE</td> + * <td>link create</td> + * <td>Properties governing link creation</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_COPY</td> + * <td>object copy</td> + * <td>Properties governing the object copying process</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_CREATE</td> + * <td>object create</td> + * <td>Properties for object creation</td> + * </tr> + * <tr> + * <td>#H5P_STRING_CREATE</td> + * <td>string create</td> + * <td>Properties for character encoding when encoding strings or + * object names</td> + * </tr> + * </table> + * + * This property list must eventually be closed with H5Pclose(); + * otherwise, errors are likely to occur. + * + * \version 1.8.15 For each class, the class name returned by + * H5Pget_class_name() was added. + * The list of possible Fortran values was updated. + * \version 1.8.0 The following property list classes were added at this + * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE, + * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE, + * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Pcreate(hid_t cls_id); +/** + * \ingroup GPLOA + * + * \brief Creates a new property list class + * + * \plistcls_id{parent} + * \param[in] name Name of property list class to register + * \param[in] create Callback routine called when a property list is + * created + * \param[in] create_data Pointer to user-defined class create data, to be + * passed along to class create callback + * \param[in] copy Callback routine called when a property list is + * copied + * \param[in] copy_data Pointer to user-defined class copy data, to be + * passed along to class copy callback + * \param[in] close Callback routine called when a property list is + * being closed + * \param[in] close_data Pointer to user-defined class close data, to be + * passed along to class close callback + * + * \return \hid_t{property list class} + * + * \details H5Pcreate_class() registers a new property list class with the + * library. The new property list class can inherit from an + * existing property list class, \p parent, or may be derived + * from the default “empty” class, NULL. New classes with + * inherited properties from existing classes may not remove + * those existing properties, only add or remove their own class + * properties. Property list classes defined and supported in the + * HDF5 library distribution are listed and briefly described in + * H5Pcreate(). The \p create routine is called when a new property + * list of this class is being created. The #H5P_cls_create_func_t + * callback function is defined as follows: + * + * \snippet this H5P_cls_create_func_t_snip + * + * The parameters to this callback function are defined as follows: + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being created</td> + * </tr> + * <tr> + * <td>\Code{void * create_data}</td> + * <td>IN: User pointer to any class creation data required</td> + * </tr> + * </table> + * + * The \p create routine is called after any registered + * \p create function is called for each property value. If the + * \p create routine returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * The \p copy routine is called when an existing property + * list of this class is copied. The #H5P_cls_copy_func_t callback + * function is defined as follows: + * \snippet this H5P_cls_copy_func_t_snip + * + * The parameters to this callback function are defined as follows: + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list created by copying</td> + * </tr> + * <tr> + * <td>\Code{void * copy_data}</td> + * <td>IN: User pointer to any class copy data required</td> + * </tr> + * </table> + * + * The \p copy routine is called after any registered \p copy function + * is called for each property value. If the \p copy routine returns a + * negative value, the new list is not returned to the user and the + * property list \p copy routine returns an error value. + * + * The \p close routine is called when a property list of this class + * is being closed. The #H5P_cls_close_func_t callback function is + * defined as follows: + * \snippet this H5P_cls_close_func_t_snip + * + * The parameters to this callback function are defined as follows: + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being closed</td> + * </tr> + * <tr> + * <td>\Code{void * close_data}</td> + * <td>IN: User pointer to any class close data required</td> + * </tr> + * </table> + * + * The \p close routine is called before any registered \p close + * function is called for each property value. If the \p close routine + * returns a negative value, the property list close routine returns + * an error value but the property list is still closed. + * + * H5Pclose_class() can be used to release the property list class + * identifier returned by this function so that resources leaks will + * not develop. + * + * \since 1.4.0 + * + */ +H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t create, void *create_data, + H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, + void *close_data); +/** + * \ingroup GPLOA + * + * \brief Compares two property lists or classes for equality + * + * \param[in] id1 First property object to be compared + * \param[in] id2 Second property object to be compared + * + * \return \htri_t + * + * \details H5Pequal() compares two property lists or classes to determine + * whether they are equal to one another. + * + * Either both \p id1 and \p id2 must be property lists or both + * must be classes; comparing a list to a class is an error. + * + * \since 1.4.0 + * + */ +H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); +/** + * \ingroup GPLOA + * + * \brief Queries whether a property name exists in a property list or + * class + * + * \param[in] plist_id Identifier for the property list or class to query + * \param[in] name Name of property to check for + * + * \return \htri_t + * + * \details H5Pexist() determines whether a property exists within a + * property list or class. + * + * \since 1.4.0 + * + */ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); -H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); -H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); -H5_DLL hid_t H5Pget_class(hid_t plist_id); -H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); +/** + * \ingroup GPLOA + * + * \brief Queries the value of a property + * + * \plist_id + * \param[in] name Name of property to query + * \param[out] value Pointer to a location to which to copy the value of + * the property + * + * \return \herr_t + * + * \details H5Pget() retrieves a copy of the value for a property in a + * property list. If there is a \p get callback routine registered + * for this property, the copy of the value of the property will + * first be passed to that routine and any changes to the copy of + * the value will be used when returning the property value from + * this routine. + * + * This routine may be called for zero-sized properties with the + * \p value set to NULL. The \p get routine will be called with + * a NULL value if the callback exists. + * + * The property name must exist or this routine will fail. + * + * If the \p get callback routine returns an error, \ value will + * not be modified. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); -H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); +/** + *\ingroup GPLO + * + * \brief Returns the property list class identifier for a property list + * + * \plist_id + * + * \return \hid_t{property list class} + * + * \details H5Pget_class() returns the property list class identifier for + * the property list identified by the \p plist_id parameter. + * + * Note that H5Pget_class() returns a value of #hid_t type, an + * internal HDF5 identifier, rather than directly returning a + * property list class. That identifier can then be used with + * either H5Pequal() or H5Pget_class_name() to determine which + * predefined HDF5 property list class H5Pget_class() has returned. + * + * A full list of valid predefined property list classes appears + * in the description of H5Pcreate(). + * + * Determining the HDF5 property list class name with H5Pequal() + * requires a series of H5Pequal() calls in an if-else sequence. + * An iterative sequence of H5Pequal() calls can compare the + * identifier returned by H5Pget_class() to members of the list of + * valid property list class names. A pseudo-code snippet might + * read as follows: + * + * \code + * plist_class_id = H5Pget_class (dsetA_plist); + * + * if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE; + * [ H5P_OBJECT_CREATE is the property list class ] + * [ returned by H5Pget_class. ] + * + * else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE; + * [ H5P_DATASET_CREATE is the property list class. ] + * + * else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE; + * [ H5P_DATASET_XFER is the property list class. ] + * + * . + * . [ Continuing the iteration until a match is found. ] + * . + * \endcode + * + * H5Pget_class_name() returns the property list class name directly + * as a string: + * + * \code + * plist_class_id = H5Pget_class (dsetA_plist); + * plist_class_name = H5Pget_class_name (plist_class_id) + * \endcode + * + * Note that frequent use of H5Pget_class_name() can become a + * performance problem in a high-performance environment. The + * H5Pequal() approach is generally much faster. + * + * \version 1.6.0 Return type changed in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Pget_class(hid_t plist_id); +/** + * \ingroup GPLOA + * + * \brief Retrieves the name of a class + * + * \plistcls_id{pclass_id} + * + * \return Returns a pointer to an allocated string containing the class + * name if successful, and NULL if not successful. + * + * \details H5Pget_class_name() retrieves the name of a generic property + * list class. The pointer to the name must be freed by the user + * with a call to H5free_memory() after each successful call. + * + * <table> + * <tr> + * <th>Class Name (class identifier) Returned</th> + * <th>Property List Class</th> + * <th>Expanded Name of the Property List Class</th> + * <th>The Class Identifier Used with H5Pcreate</th> + * <th>Comments</th> + * </tr> + * <tr> + * <td>attribute create</td> + * <td>acpl</td> + * <td>Attribute Creation Property List</td> + * <td>H5P_ATTRIBUTE_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>dataset access</td> + * <td>dapl</td> + * <td>Dataset Access Property List</td> + * <td>H5P_DATASET_ACCESS</td> + * <td> </td> + * </tr> + * <tr> + * <td>dataset create</td> + * <td>dcpl</td> + * <td>Dataset Creation Property List</td> + * <td>H5P_DATASET_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>data transfer</td> + * <td>dxpl</td> + * <td>Data Transfer Property List</td> + * <td>H5P_DATASET_XFER</td> + * <td> </td> + * </tr> + * <tr> + * <td>datatype access</td> + * <td> </td> + * <td> </td> + * <td>H5P_DATATYPE_ACCESS</td> + * <td>This class can be created, but there are no properties + * in the class currently. + * </td> + * </tr> + * <tr> + * <td>datatype create</td> + * <td> </td> + * <td> </td> + * <td>H5P_DATATYPE_CREATE</td> + * <td>This class can be created, but there + * are no properties in the class currently.</td> + * </tr> + * <tr> + * <td>file access</td> + * <td>fapl</td> + * <td>File Access Property List</td> + * <td>H5P_FILE_ACCESS</td> + * <td> </td> + * </tr> + * <tr> + * <td>file create</td> + * <td>fcpl</td> + * <td>File Creation Property List</td> + * <td>H5P_FILE_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>file mount</td> + * <td>fmpl</td> + * <td>File Mount Property List</td> + * <td>H5P_FILE_MOUNT</td> + * <td> </td> + * </tr> + * <tr> + * <td>group access</td> + * <td> </td> + * <td> </td> + * <td>H5P_GROUP_ACCESS</td> + * <td>This class can be created, but there + * are no properties in the class currently.</td> + * </tr> + * <tr> + * <td>group create</td> + * <td>gcpl</td> + * <td>Group Creation Property List</td> + * <td>H5P_GROUP_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>link access</td> + * <td>lapl</td> + * <td>Link Access Property List</td> + * <td>H5P_LINK_ACCESS</td> + * <td> </td> + * </tr> + * <tr> + * <td>link create</td> + * <td>lcpl</td> + * <td>Link Creation Property List</td> + * <td>H5P_LINK_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>object copy</td> + * <td>ocpypl</td> + * <td>Object Copy Property List</td> + * <td>H5P_OBJECT_COPY</td> + * <td> </td> + * </tr> + * <tr> + * <td>object create</td> + * <td>ocpl</td> + * <td>Object Creation Property List</td> + * <td>H5P_OBJECT_CREATE</td> + * <td> </td> + * </tr> + * <tr> + * <td>string create</td> + * <td>strcpl</td> + * <td>String Creation Property List</td> + * <td>H5P_STRING_CREATE</td> + * <td> </td> + * </tr> + * </table> + * + * \since 1.4.0 + * + */ +H5_DLL char *H5Pget_class_name(hid_t pclass_id); +/** + * \ingroup GPLOA + * + * \brief Retrieves the parent class of a property class + * + * \plistcls_id{pclass_id} + * + * \return \hid_t{parent class object} + * + * \details H5Pget_class_parent() retrieves an identifier for the parent + * class of a property class. + * + * \since 1.4.0 + * + */ +H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); +/** + * \ingroup GPLOA + * + * \brief Queries the number of properties in a property list or class + * + * \param[in] id Identifier for property object to query + * \param[out] nprops Number of properties in object + * + * \return \herr_t + * + * \details H5Pget_nprops() retrieves the number of properties in a + * property list or property list class. + * + * If \p id is a property list identifier, the current number of + * properties in the list is returned in \p nprops. + * + * If \p id is a property list class identifier, the number of + * registered properties in the class is returned in \p nprops. + * + * \since 1.4.0 + * + */ +H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); +/** + * \ingroup GPLOA + * + * \brief Queries the size of a property value in bytes + * + * \param[in] id Identifier of property object to query + * \param[in] name Name of property to query + * \param[out] size Size of property in bytes + * + * \return \herr_t + * + * \details H5Pget_size() retrieves the size of a property's value in + * bytes. This function operates on both property lists and + * property classes. + * + * Zero-sized properties are allowed and return 0. + * + * \since 1.4.0 + * + */ +H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); +/** + * \ingroup GPLOA + * + * \brief Registers a temporary property with a property list + * + * \plist_id + * \param[in] name Name of property to create + * \param[in] size Size of property in bytes + * \param[in] value Initial value for the property + * \param[in] set Callback routine called before a new value is copied + * into the property's value + * \param[in] get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_del Callback routine called when a property is deleted + * from a property list + * \param[in] copy Callback routine called when a property is copied + * from an existing property list + * \param[in] compare Callback routine called when a property is compared + * with another property list + * \param[in] close Callback routine called when a property list is + * being closed and the property value will be disposed + * of + * + * \return \herr_t + * + * \details H5Pinsert2() creates a new property in a property + * list. The property will exist only in this property list and + * copies made from it. + * + * The initial property value must be provided in \p value and + * the property value will be set accordingly. + * + * The name of the property must not already exist in this list, + * or this routine will fail. + * + * The \p set and \p get callback routines may be set to NULL + * if they are not needed. + * + * Zero-sized properties are allowed and do not store any data + * in the property list. The default value of a zero-size + * property may be set to NULL. They may be used to indicate the + * presence or absence of a particular piece of information. + * + * The \p set routine is called before a new value is copied + * into the property. The #H5P_prp_set_func_t callback function + * is defined as follows: + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to the callback function are defined as follows: + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being + * modified</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being modified</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: Pointer to new value pointer for the property + * being modified</td> + * </tr> + * </table> + * + * The \p set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p set routine returns a negative value, the new property + * value is not copied into the property and the \p set routine + * returns an error value. The \p set routine will be called for + * the initial value. + * + * \b Note: The \p set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p get + * callback would then reverse the transformation or translation. + * A single \p get or \p set callback could handle multiple + * properties by performing different actions based on the + * property name or other properties in the property list. + * + * The \p get routine is called when a value is retrieved from + * a property value. The #H5P_prp_get_func_t callback function + * is defined as follows: + * + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to the above callback function are: + * + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being queried</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being queried</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: The value of the property being returned</td> + * </tr> + * </table> + * + * The \p get routine may modify the value to be returned from + * the query and those changes will be preserved. If the \p get + * routine returns a negative value, the query routine returns + * an error value. + * + * The \p prp_del routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as follows: + * + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to the above callback function are: + * + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list the property is + * being deleted from</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property in the list</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: The value for the property being deleted</td> + * </tr> + * </table> + * + * The \p prp_del routine may modify the value passed in, but the + * value is not used by the library when the \p prp_del routine + * returns. If the \p prp_del routine returns a negative value, + * the property list \p prp_del routine returns an error value but + * the property is still deleted. + * + * The \p copy routine is called when a new property list with + * this property is being created through a \p copy operation. + * + * The #H5P_prp_copy_func_t callback function is defined as follows: + * + * \snippet this H5P_prp_cb1_t_snip + * + * The parameters to the above callback function are: + * <table> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being copied</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN/OUT: The value for the property being copied</td> + * </tr> + * </table> + * + * The \p copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If the + * \p copy routine returns a negative value, the new property value + * is not copied into the property and the copy routine returns an + * error value. + * + * The \p compare routine is called when a property list with this + * property is compared to another property list with the same + * property. + * + * The #H5P_prp_compare_func_t callback function is defined as + * follows: + * + * \snippet this H5P_prp_compare_func_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const void * value1}</td> + * <td>IN: The value of the first property to compare</td> + * </tr> + * <tr> + * <td>\Code{const void * value2}</td> + * <td>IN: The value of the second property to compare</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * </table> + * + * The \p compare routine may not modify the values. The \p compare + * routine should return a positive value if \p value1 is greater + * than \p value2, a negative value if \p value2 is greater than + * \p value1 and zero if \p value1 and \p value2 are equal. + * + * The \p close routine is called when a property list with this + * property is being closed. + * + * The #H5P_prp_close_func_t callback function is defined as follows: + * \snippet this H5P_prp_cb1_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property in the list</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: The value for the property being closed</td> + * </tr> + * </table> + * + * The \p close routine may modify the value passed in, the + * value is not used by the library when the close routine + * returns. If the \p close routine returns a negative value, + * the property list \p close routine returns an error value + * but the property list is still closed. + * + * \b Note: There is no \p create callback routine for temporary + * property list objects; the initial value is assumed to + * have any necessary setup already performed on it. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t set, + 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 + * + * \brief Determines whether a property list is a member of a class + * + * \plist_id + * \plistcls_id{pclass_id} + * + * \return \htri_t + * + * \details H5Pisa_class() checks to determine whether the property list + * \p plist_id is a member of the property list class + * \p pclass_id. + * + * \see H5Pcreate() + * + * \since 1.6.0 + * + */ 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); -H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); +/** + * \ingroup GPLOA + * + * \brief Iterates over properties in a property class or list + * + * \param[in] id Identifier of property object to iterate over + * \param[in,out] idx Index of the property to begin with + * \param[in] iter_func Function pointer to function to be called + * with each property iterated over + * \param[in,out] iter_data Pointer to iteration data from user + * + * \return On success: the return value of the last call to \p iter_func if + * it was non-zero; zero if all properties have been processed. + * On Failure, a negative value + * + * \details H5Piterate() iterates over the properties in the property + * object specified in \p id, which may be either a property + * list or a property class, performing a specified operation + * on each property in turn. + * + * For each property in the object, \p iter_func and the + * additional information specified below are passed to the + * #H5P_iterate_t operator function. + * + * The iteration begins with the \p idx-th property in the + * object; the next element to be processed by the operator + * is returned in \p idx. If \p idx is NULL, the iterator + * starts at the first property; since no stopping point is + * returned in this case, the iterator cannot be restarted if + * one of the calls to its operator returns non-zero. + * + * The prototype for the #H5P_iterate_t operator is as follows: + * \snippet this H5P_iterate_t_snip + * + * The operation receives the property list or class + * identifier for the object being iterated over, \p id, the + * name of the current property within the object, \p name, + * and the pointer to the operator data passed in to H5Piterate(), + * \p iter_data. The valid return values from an operator are + * as follows: + * + * <table> + * <tr> + * <td>Zero</td> + * <td>Causes the iterator to continue, returning zero when all + * properties have been processed</td> + * </tr> + * <tr> + * <td>Positive</td> + * <td>Causes the iterator to immediately return that positive + * value, indicating short-circuit success. The iterator + * can be restarted at the index of the next property</td> + * </tr> + * <tr> + * <td>Negative</td> + * <td>Causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the + * index of the next property</td> + * </tr> + * </table> + * H5Piterate() assumes that the properties in the object + * identified by \p id remain unchanged through the iteration. + * If the membership changes during the iteration, the function's + * behavior is undefined. + * + * \since 1.4.0 + * + */ +H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data); +/** + * \ingroup GPLOA + * + * \brief Registers a permanent property with a property list class + * + * \plistcls_id{cls_id} + * \param[in] name Name of property to register + * \param[in] size Size of property in bytes + * \param[in] def_value Default value for property in newly created + * property lists + * \param[in] create Callback routine called when a property list is + * being created and the property value will be + * initialized + * \param[in] set Callback routine called before a new value is + * copied into the property's value + * \param[in] get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_del Callback routine called when a property is deleted + * from a property list + * \param[in] copy Callback routine called when a property is copied + * from a property list + * \param[in] compare Callback routine called when a property is compared + * with another property list + * \param[in] close Callback routine called when a property list is + * being closed and the property value will be + * disposed of + * + * \return \herr_t + * + * \details H5Pregister2() registers a new property with a property list + * class. The \p cls_id identifier can be obtained by calling + * H5Pcreate_class(). The property will exist in all property + * list objects of \p cl_id created after this routine finishes. The + * name of the property must not already exist, or this routine + * will fail. The default property value must be provided and all + * new property lists created with this property will have the + * property value set to the default value. Any of the callback + * routines may be set to NULL if they are not needed. + * + * Zero-sized properties are allowed and do not store any data in + * the property list. These may be used as flags to indicate the + * presence or absence of a particular piece of information. The + * default pointer for a zero-sized property may be set to NULL. + * The property \p create and \p close callbacks are called for + * zero-sized properties, but the \p set and \p get callbacks are + * never called. + * + * The \p create routine is called when a new property list with + * this property is being created. The #H5P_prp_create_func_t + * callback function is defined as follows: + * + * \snippet this H5P_prp_cb1_t_snip + * + * The parameters to this callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being modified</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN/OUT: The default value for the property being created, + * which will be passed to H5Pregister2()</td> + * </tr> + * </table> + * + * The \p create routine may modify the value to be set and those + * changes will be stored as the initial value of the property. + * If the \p create routine returns a negative value, the new + * property value is not copied into the property and the + * \p create routine returns an error value. + * + * The \p set routine is called before a new value is copied into + * the property. The #H5P_prp_set_func_t callback function is defined + * as follows: + * + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to this callback function are defined as follows: + * + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being modified</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being modified</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void *value}</td> + * <td>IN/OUT: Pointer to new value pointer for the property + * being modified</td> + * </tr> + * </table> + * + * The \p set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p set routine returns a negative value, the new property + * value is not copied into the property and the \p set routine + * returns an error value. The \p set routine will not be called + * for the initial value; only the \p create routine will be called. + * + * \b Note: The \p set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p get + * callback would then reverse the transformation or translation. + * A single \p get or \p set callback could handle multiple + * properties by performing different actions based on the property + * name or other properties in the property list. + * + * The \p get routine is called when a value is retrieved from a + * property value. The #H5P_prp_get_func_t callback function is + * defined as follows: + * + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list being + * queried</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being queried</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN/OUT: The value of the property being returned</td> + * </tr> + * </table> + * + * The \p get routine may modify the value to be returned from the + * query and those changes will be returned to the calling routine. + * If the \p set routine returns a negative value, the query + * routine returns an error value. + * + * The \p prp_del routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as follows: + * + * \snippet this H5P_prp_cb2_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\ref hid_t \c prop_id</td> + * <td>IN: The identifier of the property list the property is + * being deleted from</td> + * </tr> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property in the list</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: The value for the property being deleted</td> + * </tr> + * </table> + * + * The \p prp_del routine may modify the value passed in, but the + * value is not used by the library when the \p prp_del routine + * returns. If the \p prp_del routine returns a negative value, + * the property list delete routine returns an error value but + * the property is still deleted. + * + * The \p copy routine is called when a new property list with + * this property is being created through a \p copy operation. + * The #H5P_prp_copy_func_t callback function is defined as follows: + * + * \snippet this H5P_prp_cb1_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property being copied</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN/OUT: The value for the property being copied</td> + * </tr> + * </table> + * + * The \p copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If + * the \p copy routine returns a negative value, the new + * property value is not copied into the property and the \p copy + * routine returns an error value. + * + * The \p compare routine is called when a property list with this + * property is compared to another property list with the same + * property. The #H5P_prp_compare_func_t callback function is + * defined as follows: + * + * \snippet this H5P_prp_compare_func_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const void * value1}</td> + * <td>IN: The value of the first property to compare</td> + * </tr> + * <tr> + * <td>\Code{const void * value2}</td> + * <td>IN: The value of the second property to compare</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * </table> + * + * The \p compare routine may not modify the values. The \p compare + * routine should return a positive value if \p value1 is greater + * than \p value2, a negative value if \p value2 is greater than + * \p value1 and zero if \p value1 and \p value2 are equal. + * + * The \p close routine is called when a property list with this + * property is being closed. The #H5P_prp_close_func_t callback + * function is defined as follows: + * + * \snippet this H5P_prp_cb1_t_snip + * + * The parameters to the callback function are defined as follows: + * + * <table> + * <tr> + * <td>\Code{const char * name}</td> + * <td>IN: The name of the property in the list</td> + * </tr> + * <tr> + * <td>\Code{size_t size}</td> + * <td>IN: The size of the property in bytes</td> + * </tr> + * <tr> + * <td>\Code{void * value}</td> + * <td>IN: The value for the property being closed</td> + * </tr> + * </table> + * + * The \p close routine may modify the value passed in, but the + * value is not used by the library when the \p close routine returns. + * If the \p close routine returns a negative value, the property + * list close routine returns an error value but the property list is + * still closed. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, + H5P_prp_create_func_t create, H5P_prp_set_func_t set, 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 + * + * \brief Removes a property from a property list + * + * \plist_id + * \param[in] name Name of property to remove + * + * \return \herr_t + * + * \details H5Premove() removes a property from a property list. Both + * properties which were in existence when the property list was + * created (i.e. properties registered with H5Pregister()) and + * properties added to the list after it was created (i.e. added + * with H5Pinsert1() may be removed from a property list. + * Properties do not need to be removed from a property list + * before the list itself is closed; they will be released + * automatically when H5Pclose() is called. + * + * If a \p close callback exists for the removed property, it + * will be called before the property is released. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); +/** + * \ingroup GPLOA + * + * \brief Sets a property list value + * + * \plist_id + * \param[in] name Name of property to modify + * \param[in] value Pointer to value to set the property to + * + * \return \herr_t + * + * \details H5Pset() sets a new value for a property in a property list. + * If there is a \p set callback routine registered for this + * property, the \p value will be passed to that routine and any + * changes to the \p value will be used when setting the property + * value. The information pointed to by the \p value pointer + * (possibly modified by the \p set callback) is copied into the + * property list value and may be changed by the application + * making the H5Pset() call without affecting the property value. + * + * The property name must exist or this routine will fail. + * + * If the \p set callback routine returns an error, the property + * value will not be modified. + * + * This routine may not be called for zero-sized properties and + * will return an error in that case. + * + * \since 1.4.0 + * + */ +H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, void *value); +/** + * \ingroup GPLOA + * + * \brief Removes a property from a property list class + * + * \plistcls_id{pclass_id} + * \param[in] name Name of property to remove + * + * \return \herr_t + * + * \details H5Punregister() removes a property from a property list class. + * Future property lists created of that class will not contain + * this property; existing property lists containing this property + * are not affected. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); -H5_DLL herr_t H5Pclose_class(hid_t plist_id); -H5_DLL herr_t H5Pclose(hid_t plist_id); -H5_DLL hid_t H5Pcopy(hid_t plist_id); /* Object creation property list (OCPL) routines */ -H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); -H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense); -H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags); + +/** + * \ingroup DCPL + * + * \brief Verifies that all required filters are available + * + * \plist_id + * + * \return \htri_t + * + * \details H5Pall_filters_avail() verifies that all of the filters set in + * the dataset or group creation property list \p plist_id are + * currently available. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.6.0 + * + */ +H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id); +/** + * \ingroup OCPL + * + * \brief Retrieves tracking and indexing settings for attribute creation + * order + * + * \plist_id + * \param[out] crt_order_flags Flags specifying whether to track and + * index attribute creation order + * + * \return \herr_t + * + * \details H5Pget_attr_creation_order() retrieves the settings for + * tracking and indexing attribute creation order on an object. + * + * \p plist_id is an object creation property list (\p ocpl), + * as it can be a dataset or group creation property list + * identifier. The term \p ocpl is used when different types + * of objects may be involved. + * + * \p crt_order_flags returns flags with the following meanings: + * + * <table> + * <tr> + * <td>#H5P_CRT_ORDER_TRACKED</td> + * <td>Attribute creation order is tracked but not necessarily + * indexed.</td> + * </tr> + * <tr> + * <td>#H5P_CRT_ORDER_INDEXED </td> + * <td>Attribute creation order is indexed (requires + * #H5P_CRT_ORDER_TRACKED).</td> + * </tr> + * </table> + * + * If \p crt_order_flags is returned with a value of 0 (zero), + * attribute creation order is neither tracked nor indexed. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags); -H5_DLL herr_t H5Pset_obj_track_times(hid_t plist_id, hbool_t track_times); +/** + * \ingroup OCPL + * + * \brief Retrieves attribute storage phase change thresholds + * + * \plist_id + * \param[out] max_compact Maximum number of attributes to be stored in + * compact storage (Default: 8) + * \param[out] min_dense Minimum number of attributes to be stored in + * dense storage (Default: 6) + * + * \return \herr_t + * + * \details H5Pget_attr_phase_change() retrieves threshold values for + * attribute storage on an object. These thresholds determine the + * point at which attribute storage changes from compact storage + * (i.e., storage in the object header) to dense storage (i.e., + * storage in a heap and indexed with a B-tree). + * + * In the general case, attributes are initially kept in compact + * storage. When the number of attributes exceeds \p max_compact, + * attribute storage switches to dense storage. If the number of + * attributes subsequently falls below \p min_dense, the + * attributes are returned to compact storage. + * + * If \p max_compact is set to 0 (zero), dense storage always used. + * + * \p plist_id is an object creation property list (\p ocpl), as it + * can be a dataset or group creation property list identifier. + * The term \p ocpl is used when different types of objects may be + * involved. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense); +/** + * \ingroup OCPL + * + * \brief Returns information about a filter in a pipeline + * + * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in + * H5Ppublic.h + * + * \ocpl_id{plist_id} + * \param[in] idx Sequence number within the filter pipeline of the filter + * for which information is sought + * \param[out] flags Bit vector specifying certain general properties of the + * filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * \param[out] filter_config Bit field, as described in H5Zget_filter_info() + * + * \return Returns a negative value on failure, and the filter identifier + * if successful (see #H5Z_filter_t): + * - #H5Z_FILTER_DEFLATE Data compression filter, + * employing the gzip algorithm + * - #H5Z_FILTER_SHUFFLE Data shuffling filter + * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the + * Fletcher32 checksum algorithm + * - #H5Z_FILTER_SZIP Data compression filter, employing the + * SZIP algorithm + * - #H5Z_FILTER_NBIT Data compression filter, employing the + * N-bit algorithm + * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the + * scale-offset algorithm + * + * \details H5Pget_filter2() returns information about a filter specified by + * its filter number, in a filter pipeline specified by the property + * list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p idx is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value if + * the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen bytes, + * the filter name will be copied into that array. The name will be + * null terminated if \p namelen is large enough. The filter name + * returned will be the name appearing in the file, the name + * registered for the filter, or an empty string. + * + * \p filter_config is the bit field described in + * H5Zget_filter_info(). + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.8.0 + * + */ +H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, unsigned int *flags /*out*/, + size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, + char name[], unsigned *filter_config /*out*/); +/** + * \ingroup OCPL + * + * \brief Returns information about the specified filter + * + * \ocpl_id{plist_id} + * \param[in] filter_id Filter identifier + * \param[out] flags Bit vector specifying certain general + * properties of the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values[] Auxiliary data for the filter + * \param[in] namelen Length of filter name and number of + * elements in \p name + * \param[out] name[] Name of filter + * \param[out] filter_config Bit field, as described in + * H5Zget_filter_info() + * + * \return \herr_t + * + * \details H5Pget_filter_by_id2() returns information about the filter + * specified in \p filter_id, a filter identifier. + * + * \p plist_id must be a dataset or group creation property list + * and \p filter_id must be in the associated filter pipeline. + * + * The \p filter_id and \p flags parameters are used in the same + * manner as described in the discussion of H5Pset_filter(). + * + * Aside from the fact that they are used for output, the + * parameters \p cd_nelmts and \p cd_values[] are used in the same + * manner as described in the discussion of H5Pset_filter(). On + * input, the \p cd_nelmts parameter indicates the number of + * entries in the \p cd_values[] array allocated by the calling + * program; on exit it contains the number of values defined by + * the filter. + * + * On input, the \p namelen parameter indicates the number of + * characters allocated for the filter name by the calling program + * in the array \p name[]. On exit \p name[] contains the name of the + * filter with one character of the name in each element of the + * array. + * + * \p filter_config is the bit field described in + * H5Zget_filter_info(). + * + * If the filter specified in \p filter_id is not set for the + * property list, an error will be returned and + * H5Pget_filter_by_id2() will fail. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t filter_id, unsigned int *flags /*out*/, + size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, + char name[] /*out*/, unsigned *filter_config /*out*/); +/** + * \ingroup OCPL + * + * \brief Returns the number of filters in the pipeline + * + * \ocpl_id{plist_id} + * + * \return Returns the number of filters in the pipeline if successful; + * otherwise returns a negative value. + * + * \details H5Pget_nfilters() returns the number of filters defined in the + * filter pipeline associated with the property list \p plist_id. + * + * In each pipeline, the filters are numbered from 0 through \Code{N-1}, + * where \c N is the value returned by this function. During output to + * the file, the filters are applied in increasing order; during + * input from the file, they are applied in decreasing order. + * + * H5Pget_nfilters() returns the number of filters in the pipeline, + * including zero (0) if there are none. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Pget_nfilters(hid_t plist_id); +/** + * \ingroup OCPL + * + * \brief Determines whether times associated with an object + * are being recorded + * + * \plist_id + * \param[out] track_times Boolean value, 1 (TRUE) or 0 (FALSE), + * specifying whether object times are being recorded + * + * \return \herr_t + * + * \details H5Pget_obj_track_times() queries the object creation property + * list, \p plist_id, to determine whether object times are being + * recorded. + * + * If \p track_times is returned as 1, times are being recorded; + * if \p track_times is returned as 0, times are not being + * recorded. + * + * Time data can be retrieved with H5Oget_info(), which will return + * it in the #H5O_info_t struct. + * + * If times are not tracked, they will be reported as follows + * when queried: 12:00 AM UDT, Jan. 1, 1970 + * + * See H5Pset_obj_track_times() for further discussion. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times); +/** + * \ingroup OCPL + * + * \brief Modifies a filter in the filter pipeline + * + * \ocpl_id{plist_id} + * \param[in] filter Filter to be modified + * \param[in] flags Bit vector specifying certain general properties + * of the filter + * \param[in] cd_nelmts Number of elements in \p cd_values + * \param[in] cd_values[] Auxiliary data for the filter + * + * \return \herr_t + * + * \details H5Pmodify_filter() modifies the specified \p filter in the + * filter pipeline. \p plist_id must be a dataset or group + * creation property list. + * + * The \p filter, \p flags \p cd_nelmts[], and \p cd_values + * parameters are used in the same manner and accept the same + * values as described in the discussion of H5Pset_filter(). + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[/*cd_nelmts*/]); +/** + * \ingroup OCPL + * + * \brief Delete one or more filters in the filter pipeline + * + * \ocpl_id{plist_id} + * \param[in] filter Filter to be deleted + * + * \return \herr_t + * + * \details H5Premove_filter() removes the specified \p filter from the + * filter pipeline in the dataset or group creation property + * list \p plist_id. + * + * The \p filter parameter specifies the filter to be removed. + * Valid values for use in \p filter are as follows: + * + * <table> + * <tr> + * <td>#H5Z_FILTER_ALL</td> + * <td>Removes all filters from the filter pipeline</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_DEFLATE</td> + * <td>Data compression filter, employing the gzip + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SHUFFLE</td> + * <td>Data shuffling filter</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_FLETCHER32</td> + * <td>Error detection filter, employing the Fletcher32 + * checksum algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SZIP</td> + * <td>Data compression filter, employing the SZIP + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_NBIT</td> + * <td>Data compression filter, employing the N-Bit + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SCALEOFFSET</td> + * <td>Data compression filter, employing the scale-offset + * algorithm</td> + * </tr> + * </table> + * + * Additionally, user-defined filters can be removed with this + * routine by passing the filter identifier with which they were + * registered with the HDF5 library. + * + * Attempting to remove a filter that is not in the filter + * pipeline is an error. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.6.3 + * + */ +H5_DLL herr_t H5Premove_filter(hid_t plist_id, H5Z_filter_t filter); +/** + * \ingroup OCPL + * + * \brief Sets tracking and indexing of attribute creation order + * + * \plist_id + * \param[in] crt_order_flags Flags specifying whether to track and index + * attribute creation order. \em Default: No + * flag set; attribute creation order is neither + * tracked not indexed + * + * \return \herr_t + * + * \details H5Pset_attr_creation_order() sets flags for tracking and + * indexing attribute creation order on an object. + * + * \p plist_id is a dataset or group creation property list + * identifier. + * + * \p crt_order_flags contains flags with the following meanings: + * + * <table> + * <tr> + * <td>#H5P_CRT_ORDER_TRACKED</td> + * <td>Attribute creation order is tracked but not necessarily + * indexed.</td> + * </tr> + * <tr> + * <td>#H5P_CRT_ORDER_INDEXED </td> + * <td>Attribute creation order is indexed (requires + * #H5P_CRT_ORDER_TRACKED).</td> + * </tr> + * </table> + * + * Default behavior is that attribute creation order is neither + * tracked nor indexed. + * + * H5Pset_attr_creation_order() can be used to set attribute + * creation order tracking, or to set attribute creation order + * tracking and indexing. + * + * \note If a creation order index is to be built, it must be specified in + * the object creation property list. HDF5 currently provides no + * mechanism to turn on attribute creation order tracking at object + * creation time and to build the index later. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags); +/** + * \ingroup OCPL + * + * \brief Sets attribute storage phase change thresholds + * + * \plist_id + * \param[in] max_compact Maximum number of attributes to be stored in + * compact storage (\em Default: 8); must be greater + * than or equal to \p min_dense + * + * \param[in] min_dense Minimum number of attributes to be stored in + * dense storage (\em Default: 6) + * + * \return \herr_t + * + * \details H5Pset_attr_phase_change() sets threshold values for attribute + * storage on an object. These thresholds determine the point at + * which attribute storage changes from compact storage (i.e., + * storage in the object header) to dense storage (i.e., storage + * in a heap and indexed with a B-tree). + * + * In the general case, attributes are initially kept in compact + * storage. When the number of attributes exceeds \p max_compact, + * attribute storage switches to dense storage. If the number of + * attributes subsequently falls below \p min_dense, the attributes + * are returned to compact storage. + * + * If \p max_compact is set to 0 (zero), dense storage is always + * used. \p min_dense must be set to 0 (zero) when \p max_compact + * is 0 (zero). + * + * \p plist_id is a dataset or group creation property list + * identifier. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); +/** + * \ingroup OCPL + * + * \brief Sets deflate (GNU gzip) compression method and compression level + * + * \ocpl_id{plist_id} + * \param[in] level Compression level + * + * \return \herr_t + * + * \details H5Pset_deflate() sets the deflate compression method and the + * compression level, \p level, for a dataset or group creation + * property list, \p plist_id. + * + * The filter identifier set in the property list is + * #H5Z_FILTER_DEFLATE. + * + * The compression level, \p level, is a value from zero to nine, + * inclusive. A compression level of 0 (zero) indicates no + * compression; compression improves but speed slows progressively + * from levels 1 through 9: + * + * <table> + * <tr> + * <th>Compression Level</th> + * <th>Gzip Action</th> + * </tr> + * <tr> + * <td>0</td> + * <td>No compression</td> + * </tr> + * <tr> + * <td>1</td> + * <td>Best compression speed; least compression</td> + * </tr> + * <tr> + * <td>2 through 8</td> + * <td>Compression improves; speed degrades</td> + * </tr> + * <tr> + * <td>9</td> + * <td>Best compression ratio; slowest speed</td> + * </tr> + * </table> + * + * Note that setting the compression level to 0 (zero) does not turn + * off use of the gzip filter; it simply sets the filter to perform + * no compression as it processes the data. + * + * HDF5 relies on GNU gzip for this compression. + * + * \version 1.8.5 Function extended to work with group creation property lists. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); +/** + * \ingroup OCPL + * + * \brief Adds a filter to the filter pipeline + * + * \ocpl_id{plist_id} + * \param[in] filter Filter identifier for the filter to be added to the + * pipeline + * \param[in] flags Bit vector specifying certain general properties of + * the filter + * \param[in] cd_nelmts Number of elements in \p c_values + * \param[in] c_values Auxiliary data for the filter + * + * \return \herr_t + * + * \details H5Pset_filter() adds the specified \p filter identifier and + * corresponding properties to the end of an output filter + * pipeline. + * + * \p plist_id must be either a dataset creation property list or + * group creation property list identifier. If \p plist_id is a + * dataset creation property list identifier, the filter is added + * to the raw data filter pipeline. + * + * If \p plist_id is a group creation property list identifier, + * the filter is added to the link filter pipeline, which filters + * the fractal heap used to store most of the link metadata in + * certain types of groups. The only predefined filters that can + * be set in a group creation property list are the gzip filter + * (#H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter + * (#H5Z_FILTER_FLETCHER32). + * + * The array \p c_values contains \p cd_nelmts integers which are + * auxiliary data for the filter. The integer values will be + * stored in the dataset object header as part of the filter + * information. + * + * The \p flags argument is a bit vector with the following + * fields specifying certain general properties of the filter: + * + * <table> + * <tr> + * <td>#H5Z_FLAG_OPTIONAL</td> + * <td>If this bit is set then the filter is optional. If the + * filter fails (see below) during an H5Dwrite() operation + * then the filter is just excluded from the pipeline for + * the chunk for which it failed; the filter will not + * participate in the pipeline during an H5Dread() of the + * chunk. This is commonly used for compression filters: + * if the filter result would be larger than the input, + * then the compression filter returns failure and the + * uncompressed data is stored in the file.<br /><br /> + * This flag should not be set for the Fletcher32 checksum + * filter as it will bypass the checksum filter without + * reporting checksum errors to an application.</td> + * </tr> + * <tr> + * <td>#H5Z_FLAG_MANDATORY</td> + * <td>If the filter is required, that is, set to mandatory, + * and the filter fails, the library’s behavior depends + * on whether the chunk cache is in use: + * \li If the chunk cache is enabled, data chunks will + * be flushed to the file during H5Dclose() and the + * library will return the failure in H5Dclose(). + * \li When the chunk cache is disabled or not big enough, + * or the chunk is being evicted from the cache, the + * failure will happen during H5Dwrite(). + * + * In each case, the library will still write to the file + * all data chunks that were processed by the filter + * before the failure occurred.<br /><br /> + * For example, assume that an application creates a + * dataset of four chunks, the chunk cache is enabled and + * is big enough to hold all four chunks, and the filter + * fails when it tries to write the fourth chunk. The + * actual flush of the chunks will happen during + * H5Dclose(), not H5Dwrite(). By the time H5Dclose() + * fails, the first three chunks will have been written + * to the file. Even though H5Dclose() fails, all the + * resources will be released and the file can be closed + * properly. <br /><br /> + * If, however, the filter fails on the second chunk, only + * the first chunk will be written to the file as nothing + * further can be written once the filter fails.</td> + * </tr> + * </table> + * The \p filter parameter specifies the filter to be set. Valid + * pre-defined filter identifiers are as follows: + * + * <table> + * <tr> + * <td>#H5Z_FILTER_DEFLATE</td> + * <td>Data compression filter, employing the gzip + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SHUFFLE</td> + * <td>Data shuffling filter</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_FLETCHER32</td> + * <td>Error detection filter, employing the Fletcher32 + * checksum algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SZIP</td> + * <td>Data compression filter, employing the SZIP + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_NBIT</td> + * <td>Data compression filter, employing the N-Bit + * algorithm</td> + * </tr> + * <tr> + * <td>#H5Z_FILTER_SCALEOFFSET</td> + * <td>Data compression filter, employing the scale-offset + * algorithm</td> + * </tr> + * </table> + * Also see H5Pset_edc_check() and H5Pset_filter_callback(). + * + * \note When a non-empty filter pipeline is used with a group creation + * property list, the group will be created with the new group file + * format. The filters will come into play only when dense storage + * is used (see H5Pset_link_phase_change()) and will be applied to + * the group’s fractal heap. The fractal heap will contain most of + * the the group’s link metadata, including link names. + * + * \note When working with group creation property lists, if you are + * adding a filter that is not in HDF5’s set of predefined filters, + * i.e., a user-defined or third-party filter, you must first + * determine that the filter will work for a group. See the + * discussion of the set local and can apply callback functions + * in H5Zregister(). + * + * \note If multiple filters are set for a property list, they will be + * applied to each chunk of raw data for datasets or each block + * of the fractal heap for groups in the order in which they were + * set. + * + * \note Filters can be applied only to chunked datasets; they cannot be + * used with other dataset storage methods, such as contiguous, + * compact, or external datasets. + * + * \note Dataset elements of variable-length and dataset region + * reference datatypes are stored in separate structures in the + * file called heaps. Filters cannot currently be applied to + * these heaps. + * + * \note <b>Filter Behavior in HDF5:</b><br /> + * Filters can be inserted into the HDF5 pipeline to perform + * functions such as compression and conversion. As such, they are + * a very flexible aspect of HDF5; for example, a user-defined + * filter could provide encryption for an HDF5 dataset. + * + * \note A filter can be declared as either required or optional. + * Required is the default status; optional status must be + * explicitly declared. + * + * \note A required filter that fails or is not defined causes an + * entire output operation to fail; if it was applied when the + * data was written, such a filter will cause an input operation + * to fail. + * + * \note The following table summarizes required filter behavior. + * <table> + * <tr> + * <th></th> + * <th>Required FILTER_X not available</th> + * <th>FILTER_X available</th> + * </tr> + * <tr> + * <td>H5Pset_<FILTER_X></td> + * <td>Will fail.</td> + * <td>Will succeed.</td> + * </tr> + * <tr> + * <td>H5Dwrite with FILTER_X set</td> + * <td>Will fail.</td> + * <td>Will succeed; FILTER_X will be applied to + * the data.</td> + * </tr> + * <tr> + * <td>H5Dread with FILTER_X set</td> + * <td>Will fail.</td> + * <td>Will succeed.</td> + * </tr> + * </table> + * \note An optional filter can be set for an HDF5 dataset even when + * the filter is not available. Such a filter can then be + * applied to the dataset when it becomes available on the + * original system or when the file containing the dataset is + * processed on a system on which it is available. + * + * \note A filter can be declared as optional through the use of the + * #H5Z_FLAG_OPTIONAL flag with H5Pset_filter(). + * + * \note Consider a situation where one is creating files that will + * normally be used only on systems where the optional (and + * fictional) filter FILTER_Z is routinely available. One can + * create those files on system A, which lacks FILTER_Z, create + * chunked datasets in the files with FILTER_Z defined in the + * dataset creation property list, and even write data to those + * datasets. The dataset object header will indicate that FILTER_Z + * has been associated with this dataset. But since system A does + * not have FILTER_Z, dataset chunks will be written without it + * being applied. + * + * \note HDF5 has a mechanism for determining whether chunks are + * actually written with the filters specified in the object + * header, so while the filter remains unavailable, system A will + * be able to read the data. Once the file is moved to system B, + * where FILTER_Z is available, HDF5 will apply FILTER_Z to any + * data rewritten or new data written in these datasets. Dataset + * chunks that have been written on system B will then be + * unreadable on system A; chunks that have not been re-written + * since being written on system A will remain readable on system + * A. All chunks will be readable on system B. + * + * \note The following table summarizes optional filter behavior. + * <table> + * <tr> + * <th></th> + * <th>FILTER_Z not available</th> + * <th>FILTER_Z available<br /> with encode and decode</th> + * <th>FILTER_Z available decode only</th> + * </tr> + * <tr> + * <td>H5Pset_<FILTER_Z></td> + * <td>Will succeed.</td> + * <td>Will succeed.</td> + * <td>Will succeed.</td> + * </tr> + * <tr> + * <td>H5Dread with FILTER_Z set</td> + * <td>Will succeed if FILTER_Z has not actually<br /> + * been applied to data.</td> + * <td>Will succeed.</td> + * <td>Will succeed.</td> + * </tr> + * <tr> + * <td>H5Dwrite with FILTER_Z set</td> + * <td>Will succeed;<br /> + * FILTER_Z will not be applied to the data.</td> + * <td>Will succeed;<br /> + * FILTER_Z will be applied to the data.</td> + * <td>Will succeed;<br /> + * FILTER_Z will not be applied to the data.</td> + * </tr> + * </table> + * \note The above principles apply generally in the use of HDF5 + * optional filters insofar as HDF5 does as much as possible to + * complete an operation when an optional filter is unavailable. + * (The SZIP filter is an exception to this rule; see H5Pset_szip() + * for details.) + * + * \see \ref_filter_pipe, \ref_group_impls + * + * \version 1.8.5 Function applied to group creation property lists. + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int c_values[]); -H5_DLL int H5Pget_nfilters(hid_t plist_id); -H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[], unsigned *filter_config /*out*/); -H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[] /*out*/, unsigned *filter_config /*out*/); -H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id); -H5_DLL herr_t H5Premove_filter(hid_t plist_id, H5Z_filter_t filter); -H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned aggression); -H5_DLL herr_t H5Pset_fletcher32(hid_t plist_id); +/** + * \ingroup OCPL + * + * \brief Sets up use of the Fletcher32 checksum filter + * + * \ocpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Pset_fletcher32() sets the Fletcher32 checksum filter in the + * dataset or group creation property list \p plist_id. + * + * \attention The Fletcher32 EDC checksum filter was added in HDF5 Release + * 1.6.0. In the original implementation, however, the checksum + * value was calculated incorrectly on little-endian systems. + * The error was fixed in HDF5 Release 1.6.3. + * + * \attention As a result of this fix, an HDF5 library of Release 1.6.0 + * through Release 1.6.2 cannot read a dataset created or written + * with Release 1.6.3 or later if the dataset was created with + * the checksum filter and the filter is enabled in the reading + * library. (Libraries of Release 1.6.3 and later understand the + * earlier error and compensate appropriately.) + * + * \attention \b Work-around: An HDF5 library of Release 1.6.2 or earlier + * will be able to read a dataset created or written with the + * checksum filter by an HDF5 library of Release 1.6.3 or later + * if the checksum filter is disabled for the read operation. + * This can be accomplished via a call to H5Pset_edc_check() + * with the value #H5Z_DISABLE_EDC in the second parameter. + * This has the obvious drawback that the application will be + * unable to verify the checksum, but the data does remain + * accessible. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.6.3 Error in checksum calculation on little-endian systems + * corrected in this release. + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_fletcher32(hid_t plist_id); +/** + * \ingroup OCPL + * + * \brief Sets the recording of times associated with an object + * + * \param[in] plist_id Object creation property list identifier + * \param[in] track_times Boolean value, 1 or 0, specifying whether object + * times are to be tracked + * + * \return \herr_t + * + * \details H5Pset_obj_track_times() sets a property in the object creation + * property list, \p plist_id, that governs the recording of times + * associated with an object. + * + * If \p track_times is set to 1, time data will be recorded. If + * \p track_times is set to 0, time data will not be recorded. + * + * Time data can be retrieved with H5Oget_info(), which will + * return it in the #H5O_info_t struct. + * + * If times are not tracked, they will be reported as follows when queried: + * \Code{ 12:00 AM UDT, Jan. 1, 1970} + * + * That date and time are commonly used to represent the beginning of the UNIX epoch. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_obj_track_times(hid_t plist_id, hbool_t track_times); /* File creation property list (FCPL) routines */ -H5_DLL herr_t H5Pget_version(hid_t plist_id, unsigned *boot /*out*/, unsigned *freelist /*out*/, - unsigned *stab /*out*/, unsigned *shhdr /*out*/); -H5_DLL herr_t H5Pset_userblock(hid_t plist_id, hsize_t size); -H5_DLL herr_t H5Pget_userblock(hid_t plist_id, hsize_t *size); -H5_DLL herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr, size_t sizeof_size); +/** + * \ingroup FCPL + * + * \brief Queries the 1/2 rank of an indexed storage B-tree + * + * \fcpl_id{plist_id} + * \param[out] ik Pointer to location to return the chunked storage B-tree + * 1/2 rank (<em>Default value of B-tree 1/2 rank: 32</em>) + * + * \return \herr_t + * + * \details H5Pget_istore_k() queries the 1/2 rank of an indexed storage + * B-tree. + * + * The argument \p ik may be the null pointer (NULL). + * This function is valid only for file creation property lists. + * + * \see H5Pset_istore_k() + * + * \version 1.6.4 \p ik parameter type changed to \em unsigned. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_istore_k(hid_t plist_id, unsigned *ik /*out*/); +/** + * \ingroup FCPL + * + * \brief Retrieves the configuration settings for a shared message index + * + * \fcpl_id{plist_id} + * \param[in] index_num Index being configured + * \param[out] mesg_type_flags Types of messages that may be stored in + * this index + * \param[out] min_mesg_size Minimum message size + * + * \return \herr_t + * + * \details H5Pget_shared_mesg_index() retrieves the message type and + * minimum message size settings from the file creation property + * list \p plist_id for the shared object header message index + * specified by \p index_num. + * + * \p index_num specifies the index. \p index_num is zero-indexed, + * so in a file with three indexes, they will be numbered 0, 1, + * and 2. + * + * \p mesg_type_flags and \p min_mesg_size will contain, + * respectively, the types of messages and the minimum size, in + * bytes, of messages that can be stored in this index. + * + * Valid message types are described in H5Pset_shared_mesg_index(). + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, + unsigned *min_mesg_size); +/** + * \ingroup FCPL + * + * \brief Retrieves the number of shared object header message indexes in file + * creation property list + * + * \fcpl_id{plist_id} + * \param[out] nindexes Number of shared object header message indexes + * available in files created with this property list + * + * \return \herr_t + * + * \details H5Pget_shared_mesg_nindexes() retrieves the number of shared + * object header message indexes in the specified file creation + * property list \p plist_id. + * + * If the value of \p nindexes is 0 (zero), shared object header + * messages are disabled in files created with this property list. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes); +/** + * \ingroup FCPL + * + * \brief Retrieves shared object header message phase change information + * + * \fcpl_id{plist_id} + * \param[out] max_list Threshold above which storage of a shared object + * header message index shifts from list to B-tree + * \param[out] min_btree Threshold below which storage of a shared object + * header message index reverts to list format + * + * \return \herr_t + * + * \details H5Pget_shared_mesg_phase_change() retrieves the threshold values + * for storage of shared object header message indexes in a file. + * These phase change thresholds determine the point at which the + * index storage mechanism changes from a more compact list format + * to a more performance-oriented B-tree format, and vice-versa. + * + * By default, a shared object header message index is initially + * stored as a compact list. When the number of messages in an + * index exceeds the specified \p max_list threshold, storage + * switches to a B-tree format for improved performance. If the + * number of messages subsequently falls below the \p min_btree + * threshold, the index will revert to the list format. + * + * If \p max_list is set to 0 (zero), shared object header message + * indexes in the file will always be stored as B-trees. + * + * \p plist_id specifies the file creation property list. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree); +/** + * \ingroup FCPL + * + * \brief Retrieves the size of the offsets and lengths used in an HDF5 + * file + * + * \fcpl_id{plist_id} + * \param[out] sizeof_addr Pointer to location to return offset size in + * bytes + * \param[out] sizeof_size Pointer to location to return length size in + * bytes + * + * \return \herr_t + * + * \details H5Pget_sizes() retrieves the size of the offsets and lengths + * used in an HDF5 file. This function is only valid for file + * creation property lists. + * + * \since 1.0.0 + * + */ H5_DLL herr_t H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr /*out*/, size_t *sizeof_size /*out*/); -H5_DLL herr_t H5Pset_sym_k(hid_t plist_id, unsigned ik, unsigned lk); +/** + * \ingroup FCPL + * + * \brief Retrieves the size of the symbol table B-tree 1/2 rank and the + * symbol table leaf node 1/2 size + * + * \fcpl_id{plist_id} + * \param[out] ik Pointer to location to return the symbol table's B-tree + * 1/2 rank (<em>Default value of B-tree 1/2 rank: 16</em>) + * \param[out] lk Pointer to location to return the symbol table's leaf + * node 1/2 size (<em>Default value of leaf node 1/2 + * size: 4</em>) + * + * \return \herr_t + * + * \details H5Pget_sym_k() retrieves the size of the symbol table B-tree + * 1/2 rank and the symbol table leaf node 1/2 size. + * + * This function is valid only for file creation property lists. + * + * If a parameter value is set to NULL, that parameter is not + * retrieved. + * + * \see H5Pset_sym_k() + * + * \version 1.6.4 \p ik parameter type changed to \em unsigned + * \version 1.6.0 The \p ik parameter has changed from type int to + * \em unsigned + * + * \since 1.0.0 + * + */ H5_DLL herr_t H5Pget_sym_k(hid_t plist_id, unsigned *ik /*out*/, unsigned *lk /*out*/); +/** + * \ingroup FCPL + * + * \brief Retrieves the size of a user block + * + * \fcpl_id{plist_id} + * \param[out] size Pointer to location to return user-block size + * + * \return \herr_t + * + * \details H5Pget_userblock() retrieves the size of a user block in a + * file creation property list. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_userblock(hid_t plist_id, hsize_t *size); +/** + * \ingroup FCPL + * + * \brief Retrieves the version information of various objects + * for a file creation property list(deprecated) + * + * \plist_id + * \param[out] boot Pointer to location to return super block version number + * \param[out] freelist Pointer to location to return global freelist version number + * \param[out] stab Pointer to location to return symbol table version number + * \param[out] shhdr Pointer to location to return shared object header version + * number + * + * \return \herr_t + * + * \deprecated Deprecated in favor of the function H5Fget_info() + * + * \details H5Pget_version() retrieves the version information of various objects + * for a file creation property list. Any pointer parameters which are + * passed as NULL are not queried. + * + * \version 1.6.4 \p boot, \p freelist, \p stab, \p shhdr parameter types + * changed to unsigned. + * + */ +H5_DLL herr_t H5Pget_version(hid_t plist_id, unsigned *boot /*out*/, unsigned *freelist /*out*/, + unsigned *stab /*out*/, unsigned *shhdr /*out*/); +/** + * \ingroup FCPL + * + * \brief Sets the size of the parameter used to control the B-trees for + * indexing chunked datasets + * + * \fcpl_id{plist_id} + * \param[in] ik 1/2 rank of chunked storage B-tree + * + * \return \herr_t + * + * \details H5Pset_istore_k() sets the size of the parameter used to + * control the B-trees for indexing chunked datasets. This + * function is valid only for file creation property lists. + * + * \p ik is one half the rank of a tree that stores chunked + * raw data. On average, such a tree will be 75% full, or have + * an average rank of 1.5 times the value of \p ik. + * + * The HDF5 library uses (\p ik*2) as the maximum # of entries + * before splitting a B-tree node. Since only 2 bytes are used + * in storing # of entries for a B-tree node in an HDF5 file, + * (\p ik*2) cannot exceed 65536. The default value for + * \p ik is 32. + * + * \version 1.6.4 \p ik parameter type changed to \p unsigned. + * \since 1.0.0 + * + */ H5_DLL herr_t H5Pset_istore_k(hid_t plist_id, unsigned ik); -H5_DLL herr_t H5Pget_istore_k(hid_t plist_id, unsigned *ik /*out*/); -H5_DLL herr_t H5Pset_shared_mesg_nindexes(hid_t plist_id, unsigned nindexes); -H5_DLL herr_t H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes); +/** + * \ingroup FCPL + * + * \brief Configures the specified shared object header message index + * + * \fcpl_id{plist_id} + * \param[in] index_num Index being configured + * \param[in] mesg_type_flags Types of messages that should be stored in + * this index + * \param[in] min_mesg_size Minimum message size + * + * \return \herr_t + * + * \details H5Pset_shared_mesg_index() is used to configure the specified + * shared object header message index, setting the types of + * messages that may be stored in the index and the minimum size + * of each message. + * + * \p plist_id specifies the file creation property list. + * + * \p index_num specifies the index to be configured. + * \p index_num is zero-indexed, so in a file with three indexes, + * they will be numbered 0, 1, and 2. + * + * \p mesg_type_flags and \p min_mesg_size specify, respectively, + * the types and minimum size of messages that can be stored in + * this index. + * + * Valid message types are as follows: + * + * <table> + * <tr> + * <td>#H5O_SHMESG_NONE_FLAG</td> + * <td>No shared messages</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_SDSPACE_FLAG</td> + * <td>Simple dataspace message</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_DTYPE_FLAG</td> + * <td>Datatype message</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_FILL_FLAG</td> + * <td>Fill value message</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_PLINE_FLAG</td> + * <td>Filter pipeline message</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_ATTR_FLAG</td> + * <td>Attribute message</td> + * </tr> + * <tr> + * <td>#H5O_SHMESG_ALL_FLAG</td> + * <td>All message types; i.e., equivalent to the following: + * (#H5O_SHMESG_SDSPACE_FLAG | #H5O_SHMESG_DTYPE_FLAG | + * #H5O_SHMESG_FILL_FLAG | #H5O_SHMESG_PLINE_FLAG | + * #H5O_SHMESG_ATTR_FLAG)</td> + * </tr> + * </table> + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size); -H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, - unsigned *min_mesg_size); +/** + * \ingroup FCPL + * + * \brief Sets number of shared object header message indexes + * + * \fcpl_id{plist_id} + * \param[in] nindexes Number of shared object header message indexes to be + * available in files created with this property list + * (\p nindexes must be <= #H5O_SHMESG_MAX_NINDEXES (8)) + * + * \return \herr_t + * + * \details H5Pset_shared_mesg_nindexes() sets the number of shared object + * header message indexes in the specified file creation property + * list. + * + * This setting determines the number of shared object header + * message indexes, \p nindexes, that will be available in files + * created with this property list. These indexes can then be + * configured with H5Pset_shared_mesg_index(). + * + * If \p nindexes is set to 0 (zero), shared object header messages + * are disabled in files created with this property list. + * + * There is a limit of #H5O_SHMESG_MAX_NINDEXES (8) that can be set + * with H5Pset_shared_mesg_nindexes(). An error will occur if + * specifying a value of \p nindexes that is greater than this value. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_shared_mesg_nindexes(hid_t plist_id, unsigned nindexes); +/** + * \ingroup FCPL + * + * \brief Sets shared object header message storage phase change thresholds + * + * \fcpl_id{plist_id} + * \param[in] max_list Threshold above which storage of a shared object + * header message index shifts from list to B-tree + * \param[in] min_btree Threshold below which storage of a shared object + * header message index reverts to list format + * + * \return \herr_t + * + * \details H5Pset_shared_mesg_phase_change() sets threshold values for + * storage of shared object header message indexes in a file. + * These phase change thresholds determine the point at which the + * index storage mechanism changes from a more compact list format + * to a more performance-oriented B-tree format, and vice-versa. + * + * By default, a shared object header message index is initially + * stored as a compact list. When the number of messages in an + * index exceeds the threshold value of \p max_list, storage + * switches to a B-tree for improved performance. If the number + * of messages subsequently falls below the \p min_btree threshold, + * the index will revert to the list format. + * + * If \p max_list is set to 0 (zero), shared object header message + * indexes in the file will be created as B-trees and will never + * revert to lists. + * + * \p plist_id specifies the file creation property list. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_shared_mesg_phase_change(hid_t plist_id, unsigned max_list, unsigned min_btree); -H5_DLL herr_t H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree); +/** + * \ingroup FCPL + * + * \brief Sets the byte size of the offsets and lengths used to address + * objects in an HDF5 file + * + * \fcpl_id{plist_id} + * \param[in] sizeof_addr Size of an object offset in bytes + * \param[in] sizeof_size Size of an object length in bytes + * + * \return \herr_t + * + * \details H5Pset_sizes() sets the byte size of the offsets and lengths + * used to address objects in an HDF5 file. This function is only + * valid for file creation property lists. Passing in a value + * of 0 for one of the parameters retains the current value. The + * default value for both values is the same as sizeof(hsize_t) + * in the library (normally 8 bytes). Valid values currently + * are 2, 4, 8 and 16. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr, size_t sizeof_size); +/** + * \ingroup FCPL + * + * \brief + * + * \fcpl_id{plist_id} + * \param[in] ik Symbol table tree rank + * \param[in] lk Symbol table node size + * + * \return \herr_t + * + * \details H5Pset_sym_k() sets the size of parameters used to control the + * symbol table nodes. + * + * This function is valid only for file creation property lists. + * Passing in a value of zero (0) for one of the parameters retains + * the current value. + * + * \p ik is one half the rank of a B-tree that stores a symbol + * table for a group. Internal nodes of the symbol table are on + * average 75% full. That is, the average rank of the tree is + * 1.5 times the value of \p ik. The HDF5 library uses (\p ik*2) as + * the maximum # of entries before splitting a B-tree node. Since + * only 2 bytes are used in storing # of entries for a B-tree node + * in an HDF5 file, (\p ik*2) cannot exceed 65536. The default value + * for \p ik is 16. + * + * \p lk is one half of the number of symbols that can be stored in + * a symbol table node. A symbol table node is the leaf of a symbol + * table tree which is used to store a group. When symbols are + * inserted randomly into a group, the group's symbol table nodes are + * 75% full on average. That is, they contain 1.5 times the number of + * symbols specified by \p lk. The default value for \p lk is 4. + * + * \version 1.6.4 \p ik parameter type changed to \em unsigned. + * \version 1.6.0 The \p ik parameter has changed from type int to + * \em unsigned. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_sym_k(hid_t plist_id, unsigned ik, unsigned lk); +/** + * \ingroup FCPL + * + * \brief Sets user block size + * + * \fcpl_id{plist_id} + * \param[in] size Size of the user-block in bytes + * + * \return \herr_t + * + * \details H5Pset_userblock() sets the user block size of a file creation + * property list. The default user block size is 0; it may be set + * to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.). + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_userblock(hid_t plist_id, hsize_t size); /* File access property list (FAPL) routines */ -H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignment); +/** + * \ingroup FAPL + * + * \brief Retrieves the current settings for alignment properties from a + * file access property list + * + * \fapl_id + * \param[out] threshold Pointer to location of return threshold value + * \param[out] alignment Pointer to location of return alignment value + * + * \return \herr_t + * + * \details H5Pget_alignment() retrieves the current settings for + * alignment properties from a file access property list. The + * \p threshold and/or \p alignment pointers may be null + * pointers (NULL). + * + * \since 1.0.0 + * + */ H5_DLL herr_t H5Pget_alignment(hid_t fapl_id, hsize_t *threshold /*out*/, hsize_t *alignment /*out*/); -H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_info); -H5_DLL hid_t H5Pget_driver(hid_t plist_id); -H5_DLL void * H5Pget_driver_info(hid_t plist_id); -H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset); -H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset); -H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type); -H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type); -H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes, - double rdcc_w0); +/** + * \ingroup FAPL + * + * \brief Queries the raw data chunk cache parameters + * + * \fapl_id{plist_id} + * \param[in,out] mdc_nelmts <i>No longer used</i> + * \param[in,out] rdcc_nslots Number of elements (objects) in the raw data + * chunk cache + * \param[in,out] rdcc_nbytes Total size of the raw data chunk cache, in + * bytes + * \param[in,out] rdcc_w0 Preemption policy + * + * \return \herr_t + * + * \details H5Pget_cache() retrieves the maximum possible number of + * elements in the raw data chunk cache, the maximum possible + * number of bytes in the raw data chunk cache, and the + * preemption policy value. + * + * Any (or all) arguments may be null pointers, in which case + * the corresponding datum is not returned. + * + * Note that the \p mdc_nelmts parameter is no longer used. + * + * \version 1.8.0 Use of the \p mdc_nelmts parameter discontinued. + * Metadata cache configuration is managed with + * H5Pset_mdc_config() and H5Pget_mdc_config() + * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nslots parameters changed + * from type int to size_t. + * + * \since 1.0.0 + * + */ H5_DLL herr_t H5Pget_cache(hid_t plist_id, int *mdc_nelmts, /* out */ size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, double *rdcc_w0); -H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); -H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); /* out */ -H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); -H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref /*out*/); -H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree); +/** + * \ingroup FAPL + * + * \brief Gets information about the write tracking feature used by + * the core VFD + * + * \fapl_id + * \param[out] is_enabled Whether the feature is enabled + * \param[out] page_size Size, in bytes, of write aggregation pages + * + * \return \herr_t + * + * \details H5Pget_core_write_tracking() retrieves information about the + * write tracking feature used by the core VFD. + * + * When a file is created or opened for writing using the core + * virtual file driver (VFD) with the backing store option turned + * on, the VFD can be configured to track changes to the file + * and only write out the modified bytes. To avoid a large number + * of small writes, the changes can be aggregated into pages of + * a user-specified size. The core VFD is also known as the + * memory VFD. The driver identifier is #H5FD_CORE. + * + * \note This function is only for use with the core VFD and must be used + * after the call to H5Pset_fapl_core(). It is an error to use this + * function with any other VFD. + * + * \note This function only applies to the backing store write operation + * which typically occurs when the file is flushed or closed. This + * function has no relationship to the increment parameter passed + * to H5Pset_fapl_core(). + * + * \note For optimum performance, the \p page_size parameter should be + * a power of two. + * + * \since 1.8.13 + * + */ +H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, size_t *page_size); +/** + * \ingroup FAPL + * + * \brief Returns low-lever driver identifier + * + * \plist_id + * + * \return \hid_t{low level driver} + * + * \details H5Pget_driver() returns the identifier of the low-level file + * driver associated with the file access property list or + * data transfer property list \p plist_id. + * + * Valid driver identifiers distributed with HDF5 are listed and + * described in the following table. + * + * <table> + * <tr> + * <th>Driver Name</th> + * <th>Driver Identifier</th> + * <th>Description</th> + * <th>Related Function</th> + * </tr> + * <tr> + * <td>POSIX</td> + * <td>#H5FD_SEC2</td> + * <td>This driver uses POSIX file-system functions like read and + * write to perform I/O to a single, permanent file on local disk + * with no system buffering. This driver is POSIX-compliant and + * is the default file driver for all systems.</td> + * <td>H5Pset_fapl_sec2()</td> + * </tr> + * <tr> + * <td>Direct</td> + * <td>#H5FD_DIRECT</td> + * <td>This is the #H5FD_SEC2 driver except data is written to or + * read from the file synchronously without being cached by the + * system.</td> + * <td>H5Pset_fapl_direct()</td> + * </tr> + * <tr> + * <td>Log</td> + * <td>#H5FD_LOG</td> + * <td>This is the #H5FD_SEC2 driver with logging capabilities.</td> + * <td>H5Pset_fapl_log()</td> + * </tr> + * <tr> + * <td>Windows</td> + * <td>#H5FD_WINDOWS</td> + * <td>This driver was modified in HDF5-1.8.8 to be a wrapper of the + * POSIX driver, #H5FD_SEC2. This change should not affect user + * applications.</td> + * <td>H5Pset_fapl_windows()</td> + * </tr> + * <tr> + * <td>STDIO</td> + * <td>#H5FD_STDIO</td> + * <td>This driver uses functions from the standard C stdio.h to + * perform I/O to a single, permanent file on local disk with + * additional system buffering.</td> + * <td>H5Pset_fapl_stdio()</td> + * </tr> + * <tr> + * <td>Memory</td> + * <td>#H5FD_CORE</td> + * <td>With this driver, an application can work with a file in + * memory for faster reads and writes. File contents are kept in + * memory until the file is closed. At closing, the memory + * version of the file can be written back to disk or abandoned. + * </td> + * <td>H5Pset_fapl_core()</td> + * </tr> + * <tr> + * <td>Family</td> + * <td>#H5FD_FAMILY</td> + * <td>With this driver, the HDF5 file’s address space is partitioned + * into pieces and sent to separate storage files using an + * underlying driver of the user’s choice. This driver is for + * systems that do not support files larger than 2 gigabytes. + * </td> + * <td>H5Pset_fapl_family()</td> + * </tr> + * <tr> + * <td>Multi</td> + * <td>#H5FD_MULTI</td> + * <td>With this driver, data can be stored in multiple files + * according to the type of the data. I/O might work better if + * data is stored in separate files based on the type of data. + * The Split driver is a special case of this driver.</td> + * <td>H5Pset_fapl_multi()</td> + * </tr> + * <tr> + * <td>Parallel</td> + * <td>#H5FD_MPIO</td> + * <td>This is the standard HDF5 file driver for parallel file + * systems. This driver uses the MPI standard for both + * communication and file I/O.</td> + * <td>H5Pset_fapl_mpio()</td> + * </tr> + * <tr> + * <td>Parallel POSIX</td> + * <td>H5FD_MPIPOSIX</td> + * <td>This driver is no longer available.</td> + * <td></td> + * </tr> + * <tr> + * <td>Stream</td> + * <td>H5FD_STREAM</td> + * <td>This driver is no longer available.</td> + * <td></td> + * </tr> + * </table> + * + * This list does not include custom drivers that might be + * defined and registered by a user. + * + * The returned driver identifier is only valid as long as the + * file driver remains registered. + * + * + * \since 1.4.0 + * + */ +H5_DLL hid_t H5Pget_driver(hid_t plist_id); +/** + * \ingroup FAPL + * + * \brief Returns a pointer to file driver information + * + * \param[in] plist_id File access or data transfer property list + * identifier + * + * \return Returns a pointer to a struct containing low-level driver + * information. Otherwise returns NULL. NULL is also returned if + * no driver-specific properties have been registered. No error + * is pushed on the stack in this case. + * + * \details H5Pget_driver_info() returns a pointer to file driver-specific + * information for the low-level driver associated with the file + * access or data transfer property list \p plist_id. + * + * The pointer returned by this function points to an “uncopied” + * struct. Driver-specific versions of that struct are defined + * for each low-level driver in the relevant source code file + * H5FD*.c. For example, the struct used for the MULTI driver is + * \c H5FD_multi_fapl_t defined in H5FDmulti.c. + * + * If no driver-specific properties have been registered, + * H5Pget_driver_info() returns NULL. + * + * \note H5Pget_driver_info() and H5Pset_driver() are used only when + * creating a virtual file driver (VFD) in the virtual file + * layer (VFL). + * + * \version 1.10.1 Return value was changed from \em void * to + * \em const \em void *. + * \version 1.8.2 Function publicized in this release; previous releases + * described this function only in the virtual file driver + * documentation. + * + */ +H5_DLL void *H5Pget_driver_info(hid_t plist_id); +/** + * \ingroup FAPL + * + * \brief Retrieves the size of the external link open file cache + * + * \fapl_id{plist_id} + * \param[out] efc_size External link open file cache size in number of files + * + * \return \herr_t + * + * \details H5Pget_elink_file_cache_size() retrieves the number of files that + * can be held open in an external link open file cache. + * + * \since 1.8.7 + * + */ +H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size); +/** + * \ingroup FAPL + * + * \brief Retrieves a data offset from the file access property list + * + * \fapl_id + * \param[out] offset Offset in bytes within the HDF5 file + * + * \return \herr_t + * + * \details H5Pget_family_offset() retrieves the value of offset from the + * file access property list \p fapl_id so that the user + * application can retrieve a file handle for low-level access to + * a particular member of a family of files. The file handle is + * retrieved with a separate call to H5Fget_vfd_handle() (or, + * in special circumstances, to H5FDget_vfd_handle(), see \ref VFL). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset); +/** + * \ingroup FAPL + * + * \brief Returns the file close degree + * + * \fapl_id + * \param[out] degree Pointer to a location to which to return the file + * close degree property, the value of \p degree + * + * \return \herr_t + * + * \details H5Pget_fclose_degree() returns the current setting of the file + * close degree property \p degree in the file access property + * list \p fapl_id. The value of \p degree determines how + * aggressively H5Fclose() deals with objects within a file that + * remain open when H5Fclose() is called to close that file. + * + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree); -H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size); -H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size /*out*/); -H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size); +/** + * \ingroup FAPL + * + * \brief Retrieves a copy of the file image designated as the initial content + * and structure of a file + * + * \fapl_id + * \param[in,out] buf_ptr_ptr On input, \c NULL or a pointer to a + * pointer to a buffer that contains the + * file image.\n On successful return, if \p buf_ptr_ptr is not + * \c NULL, \Code{*buf_ptr_ptr} will contain a pointer to a copy + * of the initial image provided in the last call to + * H5Pset_file_image() for the supplied \p fapl_id. If no initial + * image has been set, \Code{*buf_ptr_ptr} will be \c NULL. + * \param[in,out] buf_len_ptr On input, \c NULL or a pointer to a buffer + * specifying the required size of the buffer to hold the file + * image.\n On successful return, if \p buf_len_ptr was not + * passed in as \c NULL, \p buf_len_ptr will return the required + * size in bytes of the buffer to hold the initial file image in + * the supplied file access property list, \p fapl_id. If no + * initial image is set, the value of \Code{*buf_len_ptr} will be + * set to 0 (zero) + * \return \herr_t + * + * \details H5Pget_file_image() allows an application to retrieve a copy of the + * file image designated for a VFD to use as the initial contents of a file. + * + * If file image callbacks are defined, H5Pget_file_image() will use + * them when allocating and loading the buffer to return to the + * application (see H5Pset_file_image_callbacks()). If file image + * callbacks are not defined, the function will use \c malloc and \c + * memcpy. When \c malloc and \c memcpy are used, it is the caller’s + * responsibility to discard the returned buffer with a call to \c + * free. + * + * It is the responsibility of the calling application to free the + * buffer whose address is returned in \p buf_ptr_ptr. This can be + * accomplished with \c free if file image callbacks have not been set + * (see H5Pset_file_image_callbacks()) or with the appropriate method + * if file image callbacks have been set. + * + * \see H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), + * \ref H5FD_file_image_callbacks_t, \ref H5FD_file_image_op_t, + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations"> + * HDF5 File Image Operations</a>. + * + * + * \since 1.8.9 + * + */ +H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr); +/** + * \ingroup FAPL + * + * \brief Retrieves callback routines for working with file images + * + * \fapl_id + * \param[in,out] callbacks_ptr Pointer to the instance of the + * #H5FD_file_image_callbacks_t struct in which the callback + * routines are to be returned\n + * Struct fields must be initialized to NULL before the call + * is made.\n + * Struct field contents upon return will match those passed in + * in the last H5Pset_file_image_callbacks() call for the file + * access property list \p fapl_id. + * \return \herr_t + * + * \details H5Pget_file_image_callbacks() retrieves the callback routines set for + * working with file images opened with the file access property list + * \p fapl_id. + * + * The callbacks must have been previously set with + * H5Pset_file_image_callbacks() in the file access property list. + * + * Upon the successful return of H5Pset_file_image_callbacks(), the + * fields in the instance of the #H5FD_file_image_callbacks_t struct + * pointed to by \p callbacks_ptr will contain the same values as were + * passed in the most recent H5Pset_file_image_callbacks() call for the + * file access property list \p fapl_id. + * + * \see H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), + * \ref H5FD_file_image_callbacks_t, \ref H5FD_file_image_op_t, + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations"> + * HDF5 File Image Operations</a>. + * + * \since 1.8.9 + * + */ +H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); +/** + * \ingroup FAPL + * + * \brief Returns garbage collecting references setting + * + * \fapl_id + * \param[out] gc_ref Flag returning the state of reference garbage + * collection. A returned value of 1 indicates that + * garbage collection is on while 0 indicates that + * garbage collection is off. + * + * \return \herr_t + * + * \details H5Pget_gc_references() returns the current setting for the + * garbage collection references property from the specified + * file access property list. The garbage collection references + * property is set by H5Pset_gc_references(). + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref /*out*/); +/** + * \ingroup FAPL + * + * \brief Retrieves library version bounds settings that indirectly control + * the format versions used when creating objects + * + * \fapl_id{plist_id} + * \param[out] low The earliest version of the library that will be used + * for writing objects + * \param[out] high The latest version of the library that will be used for + * writing objects + * + * \return \herr_t + * + * \details H5Pget_libver_bounds() retrieves the lower and upper bounds on + * the HDF5 library release versions that indirectly determine the + * object format versions used when creating objects in the file. + * + * This property is retrieved from the file access property list + * specified by the parameter \p fapl_id. + * + * The value returned in the parameters \p low and \p high is one + * of the enumerated values in the #H5F_libver_t struct, which is + * defined in H5Fpublic.h. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high); +/** + * \ingroup FAPL + * + * \brief Get the current initial metadata cache configuration from the + * provided file access property list + * + * \fapl_id{plist_id} + * \param[in,out] config_ptr Pointer to the instance of #H5AC_cache_config_t + * in which the current metadata cache configuration is to be + * reported + * \return \herr_t + * + * \note The \c in direction applies only to the \ref H5AC_cache_config_t.version + * field. All other fields are \c out parameters. + * + * \details The fields of the #H5AC_cache_config_t structure are shown + * below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * H5Pget_mdc_config() gets the initial metadata cache configuration + * contained in a file access property list and loads it into the + * instance of #H5AC_cache_config_t pointed to by the \p config_ptr + * parameter. This configuration is used when the file is opened. + * + * Note that the version field of \Code{*config_ptr} must be + * initialized; this allows the library to support earlier versions of + * the #H5AC_cache_config_t structure. + * + * See the overview of the metadata cache in the special topics section + * of the user guide for details on the configuration data returned. If + * you haven't read and understood that documentation, the results of + * this call will not make much sense. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup FAPL + * + * \brief Returns the current metadata block size setting + * + * \fapl_id{fapl_id} + * \param[out] size Minimum size, in bytes, of metadata block allocations + * + * \return \herr_t + * + * \details Returns the current minimum size, in bytes, of new + * metadata block allocations. This setting is retrieved from the + * file access property list \p fapl_id. + * + * This value is set by H5Pset_meta_block_size() and is + * retrieved from the file access property list \p fapl_id. + * + * \since 1.4.0 + */ +H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size); +/** + * \ingroup FAPL + * + * \brief Retrieves type of data property for MULTI driver + * + * \param[in] fapl_id File access property list or data transfer property + * list identifier + * \param[out] type Type of data + * + * \return \herr_t + * + * \details H5Pget_multi_type() retrieves the type of data setting from + * the file access or data transfer property list \p fapl_id. + * This enables a user application to specify the type of data + * the application wishes to access so that the application can + * retrieve a file handle for low-level access to the particular + * member of a set of MULTI files in which that type of data is + * stored. The file handle is retrieved with a separate call to + * H5Fget_vfd_handle() (or, in special circumstances, to + * H5FDget_vfd_handle(); see the Virtual File Layer documentation + * for more information. + * + * The type of data returned in \p type will be one of those + * listed in the discussion of the \p type parameter in the the + * description of the function H5Pset_multi_type(). + * + * Use of this function is only appropriate for an HDF5 file + * written as a set of files with the MULTI file driver. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type); +/** + * \ingroup FAPL + * + * \brief Returns maximum data sieve buffer size + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of data sieve buffer + * + * \return \herr_t + * + * \details H5Pget_sieve_buf_size() retrieves, size, the current maximum + * size of the data sieve buffer. + * + * This value is set by H5Pset_sieve_buf_size() and is retrieved + * from the file access property list fapl_id. + * + * \version 1.6.0 The \p size parameter has changed from type \c hsize_t + * to \c size_t + * \since 1.4.0 + */ H5_DLL herr_t H5Pget_sieve_buf_size(hid_t fapl_id, size_t *size /*out*/); -H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size); +/** + * \ingroup FAPL + * + * \brief Retrieves the current small data block size setting + * + * \fapl_id{fapl_id} + * \param[out] size Maximum size, in bytes, of the small data block + * + * \result \herr_t + * + * \details H5Pget_small_data_block_size() retrieves the current setting + * for the size of the small data block. + * + * If the returned value is zero (0), the small data block + * mechanism has been disabled for the file. + * + * \since 1.4.4 + */ H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size /*out*/); -H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high); -H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high); +/** + * \ingroup FAPL + * + * \brief Sets alignment properties of a file access property list + * + * \fapl_id + * \param[in] threshold Threshold value. Note that setting the threshold + * value to 0 (zero) has the effect of a special case, + * forcing everything to be aligned + * \param[in] alignment Alignment value + * + * \return \herr_t + * + * \details H5Pset_alignment() sets the alignment properties of a + * file access property list so that any file object greater + * than or equal in size to \p threshold bytes will be aligned + * on an address which is a multiple of \p alignment. The + * addresses are relative to the end of the user block; the + * alignment is calculated by subtracting the user block size + * from the absolute file address and then adjusting the address + * to be a multiple of \p alignment. + * + * Default values for \p threshold and \p alignment are one, + * implying no alignment. Generally the default values will + * result in the best performance for single-process access to + * the file. For MPI IO and other parallel systems, choose an + * alignment which is a multiple of the disk block size. + * + * If the file space handling strategy is set to + * #H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this + * routine is ignored. The file space handling strategy is set + * by H5Pset_file_space_strategy(). + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignment); +/** + * \ingroup FAPL + * + * \brief Sets the raw data chunk cache parameters + * + * \fapl_id{plist_id} + * \param[in] mdc_nelmts No longer used; any value passed is ignored + * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk + * cache for this dataset. Increasing this value + * reduces the number of cache collisions, but + * slightly increases the memory used. Due to the + * hashing strategy, this value should ideally be a + * prime number. As a rule of thumb, this value + * should be at least 10 times the number of chunks + * that can fit in \p rdcc_nbytes bytes. For + * maximum performance, this value should be set + * approximately 100 times that number of chunks. + * The default value is 521. + * \param[in] rdcc_nbytes Total size of the raw data chunk cache in bytes. + * The default size is 1 MB per dataset. + * \param[in] rdcc_w0 The chunk preemption policy for all datasets. + * This must be between 0 and 1 inclusive and + * indicates the weighting according to which chunks + * which have been fully read or written are + * penalized when determining which chunks to flush + * from cache. A value of 0 means fully read or + * written chunks are treated no differently than + * other chunks (the preemption is strictly LRU) + * while a value of 1 means fully read or written + * chunks are always preempted before other chunks. + * If your application only reads or writes data once, + * this can be safely set to 1. Otherwise, this should + * be set lower depending on how often you re-read or + * re-write the same data. The default value is 0.75. + * If the value passed is #H5D_CHUNK_CACHE_W0_DEFAULT, + * then the property will not be set on the dataset + * access property list, and the parameter will come + * from the file access property list. + * + * \return \herr_t + * + * \details H5Pset_cache() sets the number of elements, the total number of + * bytes, and the preemption policy value for all datasets in a file + * on the file’s file access property list. + * + * The raw data chunk cache inserts chunks into the cache by first + * computing a hash value using the address of a chunk and then by + * using that hash value as the chunk’s index into the table of + * cached chunks. In other words, the size of this hash table and the + * number of possible hash values is determined by the \p rdcc_nslots + * parameter. If a different chunk in the cache has the same hash value, + * a collision will occur, which will reduce efficiency. If inserting + * the chunk into the cache would cause the cache to be too big, then + * the cache will be pruned according to the \p rdcc_w0 parameter. + * + * The \p mdc_nelmts parameter is no longer used; any value passed + * in that parameter will be ignored. + * + * \b Motivation: Setting raw data chunk cache parameters + * can be done with H5Pset_cache(), H5Pset_chunk_cache(), + * or a combination of both. H5Pset_cache() is used to + * adjust the chunk cache parameters for all datasets via + * a global setting for the file, and H5Pset_chunk_cache() + * is used to adjust the chunk cache parameters for + * individual datasets. When both are used, parameters + * set with H5Pset_chunk_cache() will override any parameters + * set with H5Pset_cache(). + * + * \note Optimum chunk cache parameters may vary widely depending + * on different data layout and access patterns. For datasets + * with low performance requirements for example, changing + * the cache settings can save memory. + * + * \note Note: Raw dataset chunk caching is not currently + * supported when using the MPI I/O and MPI POSIX file drivers + * in read/write mode; see H5Pset_fapl_mpio() and + * H5Pset_fapl_mpiposix(), respectively. When using one of these + * file drivers, all calls to H5Dread() and H5Dwrite() will access + * the disk directly, and H5Pset_cache() will have no effect on + * performance. + * + * \note Raw dataset chunk caching is supported when these drivers are + * used in read-only mode. + * + * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). + * + * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. + * Metadata cache configuration is managed with + * H5Pset_mdc_config() and H5Pget_mdc_config(). + * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nelmts parameters + * changed from type int to size_t. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes, + double rdcc_w0); +/** + * \ingroup FAPL + * + * \brief Sets write tracking information for core driver, #H5FD_CORE + * + * \fapl_id{fapl_id} + * \param[in] is_enabled Boolean value specifying whether feature is + enabled + * \param[in] page_size Positive integer specifying size, in bytes, of + * write aggregation pages Value of 1 (one) enables + * tracking with no paging. + * + * \return \herr_t + * + * \details When a file is created or opened for writing using the core + * virtual file driver (VFD) with the backing store option + * turned on, the core driver can be configured to track + * changes to the file and write out only the modified bytes. + * + * This write tracking feature is enabled and disabled with \p + * is_enabled. The default setting is that write tracking is + * disabled, or off. + * + * To avoid a large number of small writes, changes can + * be aggregated into pages of a user-specified size, \p + * page_size. + * + * Setting \p page_size to 1 enables tracking with no page + * aggregation. + * + * The backing store option is set via the function + * H5Pset_fapl_core. + * + * \attention + * \parblock + * This function is only for use with the core VFD and must + * be used after the call to H5Pset_fapl_core(). It is an error + * to use this function with any other VFD. + * + * It is an error to use this function when the backing store + * flag has not been set using H5Pset_fapl_core(). + * + * This function only applies to the backing store write + * operation which typically occurs when the file is flushed + * or closed. This function has no relationship to the + * increment parameter passed to H5Pset_fapl_core(). + * + * For optimum performance, the \p page_size parameter should be + * a power of two. + * + * It is an error to set the page size to 0. + * \endparblock + * + * \version 1.8.14 C function modified in this release to return error + * if \p page_size is set to 0 (zero). + * \since 1.8.13 + * + */ +H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size); +/** + * \ingroup FAPL + * + * \brief Sets a file driver + * + * \plist_id + * \param[in] driver_id The new driver identifier + * \param[in] driver_info Optional struct containing driver properties + * + * \return \herr_t + * + * \details H5Pset_driver() sets the file driver, driver_id, for a file + * access or data transfer property list, \p plist_id, and + * supplies an optional struct containing the driver-specific + * properties, \p driver_info. + * + * The driver properties will be copied into the property list + * and the reference count on the driver will be incremented, + * allowing the caller to close the driver identifier but still + * use the property list. + * + * \version 1.8.2 Function publicized in this release; previous releases + * described this function only in the virtual file driver + * documentation. + * + */ +H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_info); +/** + * \ingroup FAPL + * + * \brief Sets the number of files that can be held open in an external + * link open file cache + * + * \par Motivation + * \parblock + * The <em>external link open file cache</em> holds files open after + * they have been accessed via an external link. This cache reduces + * the number of times such files are opened when external links are + * accessed repeatedly and can siginificantly improves performance in + * certain heavy-use situations and when low-level file opens or closes + * are expensive. + * + * H5Pset_elink_file_cache_size() sets the number of files + * that will be held open in an external link open file + * cache. H5Pget_elink_file_cache_size() retrieves the size of an existing + * cache; and H5Fclear_elink_file_cache() clears an existing cache without + * closing it. + * \endparblock + * + * \fapl_id{plist_id} + * \param[in] efc_size External link open file cache size in number of files + * <em>Default setting is 0 (zero).</em> + * + * \return \herr_t + * + * \details H5Pset_elink_file_cache_size() specifies the number of files + * that will be held open in an external link open file cache. + * + * The default external link open file cache size is 0 (zero), + * meaning that files accessed via an external link are not + * held open. Setting the cache size to a positive integer + * turns on the cache; setting the size back to zero turns it + * off. + * + * With this property set, files are placed in the external + * link open file cache cache when they are opened via an + * external link. Files are then held open until either + * they are evicted from the cache or the parent file is + * closed. This property setting can improve performance when + * external links are repeatedly accessed. + * + * When the cache is full, files will be evicted using a least + * recently used (LRU) scheme; the file which has gone the + * longest time without being accessed through the parent file + * will be evicted and closed if nothing else is holding that + * file open. + * + * Files opened through external links inherit the parent + * file’s file access property list by default, and therefore + * inherit the parent file’s external link open file cache + * setting. + * + * When child files contain external links of their own, the + * caches can form a graph of cached external files. Closing + * the last external reference to such a graph will recursively + * close all files in the graph, even if cycles are present. + * \par Example + * \parblock + * The following code sets up an external link open file cache that will + * hold open up to 8 files reached through external links: + * + * \code + * status = H5Pset_elink_file_cache_size(fapl_id, 8); + * \endcode + * \endparblock + * + * \since 1.8.7 + */ H5_DLL herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size); -H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size); +/** + * \ingroup FAPL + * + * \brief Sets offset property for low-level access to a file in a family of + * files + * + * \fapl_id + * \param[in] offset Offset in bytes within the HDF5 file + * + * \return \herr_t + * + * \details H5Pset_family_offset() sets the offset property in the file access + * property list \p fapl_id so that the user application can + * retrieve a file handle for low-level access to a particular member + * of a family of files. The file handle is retrieved with a separate + * call to H5Fget_vfd_handle() (or, in special circumstances, to + * H5FDget_vfd_handle(); see \ref VFL). + * + * The value of \p offset is an offset in bytes from the beginning of + * the HDF5 file, identifying a user-determined location within the + * HDF5 file. + * The file handle the user application is seeking is for the specific + * member-file in the associated family of files to which this offset + * is mapped. + * + * Use of this function is only appropriate for an HDF5 file written as + * a family of files with the \c FAMILY file driver. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset); +/** + * \ingroup FAPL + * + * \brief Sets the file close degree + * + * \fapl_id + * \param[in] degree Pointer to a location containing the file close + * degree property, the value of \p degree + * + * \return \herr_t + * + * \details H5Pset_fclose_degree() sets the file close degree property + * \p degree in the file access property list \p fapl_id. + * + * The value of \p degree determines how aggressively + * H5Fclose() deals with objects within a file that remain open + * when H5Fclose() is called to close that file. \p degree can + * have any one of four valid values: + * + * <table> + * <tr> + * <th>Degree name</th> + * <th>H5Fclose behavior with no open object in file</th> + * <th>H5Fclose behavior with open object(s) in file</th> + * </tr> + * <tr> + * <td>#H5F_CLOSE_WEAK</td> + * <td>Actual file is closed.</td> + * <td>Access to file identifier is terminated; actual file + * close is delayed until all objects in file are closed + * </td> + * </tr> + * <tr> + * <td>#H5F_CLOSE_SEMI</td> + * <td>Actual file is closed.</td> + * <td>Function returns FAILURE</td> + * </tr> + * <tr> + * <td>#H5F_CLOSE_STRONG</td> + * <td>Actual file is closed.</td> + * <td>All open objects remaining in the file are closed then + * file is closed</td> + * </tr> + * <tr> + * <td>#H5F_CLOSE_DEFAULT</td> + * <td>The VFL driver chooses the behavior. Currently, all VFL + * drivers set this value to #H5F_CLOSE_WEAK, except for the + * MPI-I/O driver, which sets it to #H5F_CLOSE_SEMI.</td> + * <td></td> + * </tr> + * + * </table> + * \warning If a file is opened multiple times without being closed, each + * open operation must use the same file close degree setting. + * For example, if a file is already open with #H5F_CLOSE_WEAK, + * an H5Fopen() call with #H5F_CLOSE_STRONG will fail. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree); +/** + * \ingroup FAPL + * + * \brief Sets an initial file image in a memory buffer + * + * \fapl_id + * \param[in] buf_ptr Pointer to the initial file image, or + * NULL if no initial file image is desired + * \param[in] buf_len Size of the supplied buffer, or + * 0 (zero) if no initial image is desired + * + * \return \herr_t + * + * \details H5Pset_file_image() allows an application to provide a file image + * to be used as the initial contents of a file. + * Calling H5Pset_file_image()makes a copy of the buffer specified in + * \p buf_ptr of size \p buf_len. + * + * \par Motivation: + * H5Pset_file_image() and other elements of HDF5 are + * used to load an image of an HDF5 file into system memory and open + * that image as a regular HDF5 file. An application can then use the + * file without the overhead of disk I/O. + * + * \par Recommended Reading: + * This function is part of the file image + * operations feature set. It is highly recommended to study the guide + * [<em>HDF5 File Image Operations</em>] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations + * ) before using this feature set. See the “See Also” section below + * for links to other elements of HDF5 file image operations. + * + * \see + * \li H5LTopen_file_image() + * \li H5Fget_file_image() + * \li H5Pget_file_image() + * \li H5Pset_file_image_callbacks() + * \li H5Pget_file_image_callbacks() + * + * \li [HDF5 File Image Operations] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations) + * in [Advanced Topics in HDF5] + * (https://portal.hdfgroup.org/display/HDF5/Advanced+Topics+in+HDF5) + * + * \li Within H5Pset_file_image_callbacks(): + * \li Callback #H5FD_file_image_callbacks_t + * \li Callback #H5FD_file_image_op_t + * + * \version 1.8.13 Fortran subroutine added in this release. + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len); -H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr); +/** + * \ingroup FAPL + * + * \brief Sets the callbacks for working with file images + * + * \note **Motivation:** H5Pset_file_image_callbacks() and other elements + * of HDF5 are used to load an image of an HDF5 file into system + * memory and open that image as a regular HDF5 file. An application + * can then use the file without the overhead of disk I/O.\n + * **Recommended Reading:** This function is part of the file + * image operations feature set. It is highly recommended to study + * the guide [HDF5 File Image Operations] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations + * ) before using this feature set. See the “See Also” section below + * for links to other elements of HDF5 file image operations. + * + * \fapl_id + * \param[in,out] callbacks_ptr Pointer to the instance of the + * #H5FD_file_image_callbacks_t structure + * + * \return \herr_t \n + * **Failure Modes**: Due to interactions between this function and + * H5Pset_file_image() and H5Pget_file_image(), + * H5Pset_file_image_callbacks() will fail if a file image has + * already been set in the target file access property list, \p fapl_id. + * + * \details H5Pset_file_image_callbacks() sets callback functions for working + * with file images in memory. + * + * H5Pset_file_image_callbacks() allows an application to control the + * management of file image buffers through user defined callbacks. + * These callbacks can be used in the management of file image buffers + * in property lists and with certain file drivers. + * + * H5Pset_file_image_callbacks() must be used before any file image has + * been set in the file access property list. Once a file image has + * been set, the function will fail. + * + * The callback routines set up by H5Pset_file_image_callbacks() are + * invoked when a new file image buffer is allocated, when an existing + * file image buffer is copied or resized, or when a file image buffer + * is released from use. + * + * Some file drivers allow the use of user-defined callback functions + * for allocating, freeing, and copying the driver’s internal buffer, + * potentially allowing optimizations such as avoiding large \c malloc + * and \c memcpy operations, or to perform detailed logging. + * + * From the perspective of the HDF5 library, the operations of the + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc", + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy", + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc", and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" callbacks + * must be identical to those of the + * corresponding C standard library calls (\c malloc, \c memcpy, + * \c realloc, and \c free). While the operations must be identical, + * the file image callbacks have more parameters. The return values + * of \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" and + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" are identical to + * the return values of \c malloc and \c realloc. The return values of + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" differ from the return + * values of \c memcpy and \c free in that the return values of + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" can also indicate failure. + * + * The callbacks and their parameters, along with a struct and + * an \c ENUM required for their use, are described below. + * + * <b>Callback struct and \c ENUM:</b> + * + * The callback functions set up by H5Pset_file_image_callbacks() use + * a struct and an \c ENUM that are defined as follows + * + * The struct #H5FD_file_image_callbacks_t serves as a container + * for the callback functions and a pointer to user-supplied data. + * The struct is defined as follows: + * \snippet H5FDpublic.h H5FD_file_image_callbacks_t_snip + * + * Elements of the #H5FD_file_image_op_t are used by the + * callbacks to invoke certain operations on file images. The ENUM is + * defined as follows: + * \snippet H5FDpublic.h H5FD_file_image_op_t_snip + * + * The elements of the #H5FD_file_image_op_t are used in the following + * callbacks: + * + * - The \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" callback + * contains a pointer to a function that must appear to HDF5 to have + * functionality identical to that of the standard C library \c malloc() call. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_malloc_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" + * callback contains a pointer to a function + * that must appear to HDF5 to have functionality identical to that + * of the standard C library \c memcopy() call, except that it returns + * a \p NULL on failure. (The \c memcpy C Library routine is defined + * to return the \p dest parameter in all cases.) + * + * - Setting \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" + * to \c NULL indicates that HDF5 should invoke + * the standard C library \c memcpy() routine when copying buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_memcpy_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" callback + * contains a pointer to a function that must appear to HDF5 to have + * functionality identical to that of the standard C library \c realloc() call. + * + * - Setting \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" + * to \p NULL indicates that HDF5 should + * invoke the standard C library \c realloc() routine when resizing + * file image buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_realloc_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_free "image_free" callback contains + * a pointer to a function that must appear to HDF5 to have functionality + * identical to that of the standard C library \c free() call, except + * that it will return \c 0 (\c SUCCEED) on success and \c -1 (\c FAIL) on failure. + * + * - Setting \ref H5FD_file_image_callbacks_t.image_free "image_free" + * to \c NULL indicates that HDF5 should invoke + * the standard C library \c free() routine when releasing file image + * buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_free_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.udata_copy "udata_copy" + * callback contains a pointer to a function + * that, from the perspective of HDF5, allocates a buffer of suitable + * size, copies the contents of the supplied \p udata into the new + * buffer, and returns the address of the new buffer. The function + * returns NULL on failure. This function is necessary if a non-NULL + * \p udata parameter is supplied, so that property lists containing + * the image callbacks can be copied. If the \p udata parameter below + * is \c NULL, then this parameter should be \c NULL as well. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h udata_copy_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.udata_free "udata_free" + * callback contains a pointer to a function + * that, from the perspective of HDF5, frees a user data block. This + * function is necessary if a non-NULL udata parameter is supplied so + * that property lists containing image callbacks can be discarded + * without a memory leak. If the udata parameter below is \c NULL, + * this parameter should be \c NULL as well. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h udata_free_snip + * + * - \p **udata**, the final field in the #H5FD_file_image_callbacks_t + * struct, provides a pointer to user-defined data. This pointer will + * be passed to the + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc", + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy", + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc", and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" callbacks. + * Define udata as \c NULL if no user-defined data is provided. + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); -H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); +/** + * \ingroup FAPL + * + * \brief Sets garbage collecting references flag + * + * \fapl_id + * \param[in] gc_ref Flag setting reference garbage collection to on (1) or off (0) + * + * \return \herr_t + * + * \details H5Pset_gc_references() sets the flag for garbage collecting + * references for the file. + * + * Dataset region references and other reference types use space in an + * HDF5 file's global heap. If garbage collection is on and the user + * passes in an uninitialized value in a reference structure, the heap + * might get corrupted. When garbage collection is off, however, and + * the user re-uses a reference, the previous heap block will be + * orphaned and not returned to the free heap space. + * + * When garbage collection is on, the user must initialize the + * reference structures to 0 or risk heap corruption. + * + * The default value for garbage collecting references is off. + * + */ +H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); +/** + * \ingroup FAPL + * + * \brief Controls the range of library release versions used when creating + * objects in a file + * + * \fapl_id{plist_id} + * \param[in] low The earliest version of the library that will be used + * for writing objects + * \param[in] high The latest version of the library that will be used for + * writing objects + * + * \return \herr_t + * + * \details H5Pset_libver_bounds() controls the range of library release + * versions that will be used when creating objects in a file. + * The object format versions are determined indirectly from the + * library release versions specified in the call. + * + * This property is set in the file access property list + * specified by the parameter \p fapl_id. + * + * The parameter \p low sets the earliest possible format + * versions that the library will use when creating objects in + * the file. Note that earliest possible is different from + * earliest, as some features introduced in library versions + * later than 1.0.0 resulted in updates to object formats. + * The parameter \p high sets the latest format versions that + * the library will be allowed to use when creating objects in + * the file. + * + * The parameters \p low and \p high must be one of the + * enumerated values in the #H5F_libver_t struct, which is + * defined in H5Fpublic.h. + * + * The macro #H5F_LIBVER_LATEST is aliased to the highest + * enumerated value in #H5F_libver_t, indicating that this is + * currently the latest format available. + * + * The library supports the following five pairs of + * (\p low, \p high) combinations as derived from the values + * in #H5F_libver_t: + * + * <table> + * <tr> + * <th>Value of \p low and \p high</th> + * <th>Result</th> + * </tr> + * <tr> + * <td>\p low=#H5F_LIBVER_EARLIEST<br /> + * <td> + * \li The library will create objects with the earliest + * possible format versions. + * \li The library will allow objects to be created with the + * latest format versions available to library release 1.8.x. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.8.x + * release will fail. + * </td> + * </tr> + * <tr> + * <td>\p low=#H5F_LIBVER_EARLIEST<br /> + * <td> + * \li The library will create objects with the earliest possible + * format versions. + * \li This is the library default setting and provides the greatest + * format compatibility. + * </td> + * </tr> + * </table> + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high); +/** + * \ingroup FAPL + * + * \brief Set the initial metadata cache configuration in the indicated File + * Access Property List to the supplied value + * + * \fapl_id{plist_id} + * \param[in] config_ptr Pointer to the instance of \p H5AC_cache_config_t + * containing the desired configuration + * \return \herr_t + * + * \details The fields of the #H5AC_cache_config_t structure are shown + * below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * \details H5Pset_mdc_config() attempts to set the initial metadata cache + * configuration to the supplied value. It will fail if an invalid + * configuration is detected. This configuration is used when the file + * is opened. + * + * See the overview of the metadata cache in the special topics section + * of the user manual for details on what is being configured. If you + * have not read and understood that documentation, you really should + * not be using this API call. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup FAPL + * + * \brief Sets the minimum metadata block size + * + * \fapl_id{fapl_id} + * \param[in] size Minimum size, in bytes, of metadata block allocations + * + * \return \herr_t + * + * \details H5Pset_meta_block_size() sets the minimum size, in bytes, of + * metadata block allocations when #H5FD_FEAT_AGGREGATE_METADATA is set by a VFL + * driver. -H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size); -H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, size_t *page_size); + * Each raw metadata block is initially allocated to be of the given size. + * Specific metadata objects (e.g., object headers, local heaps, B-trees) are then + * sub-allocated from this block. + * + * The default setting is 2048 bytes, meaning that the library will + * attempt to aggregate metadata in at least 2K blocks in the file. + * Setting the value to zero (\Code{0}) with this function will turn + * off metadata aggregation, even if the VFL driver attempts to use the + * metadata aggregation strategy. + * + * Metadata aggregation reduces the number of small data objects in the file that + * would otherwise be required for metadata. The aggregated block of metadata is + * usually written in a single write action and always in a contiguous block, + * potentially significantly improving library and application performance. + * + * \since 1.4.0 + */ +H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size); +/** + * \ingroup FAPL + * + * \brief Specifies type of data to be accessed via the \Code{MULTI} driver, + * enabling more direct access + * + * \fapl_id{fapl_id} + * \param[in] type Type of data to be accessed + * + * \return \herr_t + * + * \details H5Pset_multi_type() sets the \Emph{type of data} property in the file + * access property list \p fapl_id. This setting enables a user + * application to specify the type of data the application wishes to + * access so that the application can retrieve a file handle for + * low-level access to the particular member of a set of \Code{MULTI} + * files in which that type of data is stored. The file handle is + * retrieved with a separate call to H5Fget_vfd_handle() (or, in special + * circumstances, to H5FDget_vfd_handle(); see \ref VFL. + * + * The type of data specified in \p type may be one of the following: + * + * <table> + * <tr> + * <td>#H5FD_MEM_SUPER</td> <td>Super block data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_BTREE</td> <td>B-tree data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DRAW</td> <td>Dataset raw data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_GHEAP</td> <td>Global heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_LHEAP</td> <td>Local Heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_OHDR</td> <td>Object header data</td> + * </tr> + * </table> + * + * This function is for use only when accessing an HDF5 file written as a set of + * files with the \Code{MULTI} file driver. + * + * \since 1.6.0 + */ +H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type); +/** + * \ingroup FAPL + * + * \brief Sets the maximum size of the data sieve buffer + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of data sieve buffer + * + * \return \herr_t + * + * \details H5Pset_sieve_buf_size() sets \p size, the maximum size in bytes of the + * data sieve buffer, which is used by file drivers that are capable of + * using data sieving. + * + * The data sieve buffer is used when performing I/O on datasets in the + * file. Using a buffer which is large enough to hold several pieces of + * the dataset being read in for hyperslab selections boosts + * performance by quite a bit. + * + * The default value is set to 64KB, indicating that file I/O for raw + * data reads and writes will occur in at least 64KB blocks. Setting + * the value to zero (\Code{0}) with this API function will turn off + * the data sieving, even if the VFL driver attempts to use that + * strategy. + * + * Internally, the library checks the storage sizes of the datasets in + * the file. It picks the smaller one between the size from the file + * access property and the size of the dataset to allocate the sieve + * buffer for the dataset in order to save memory usage. + * + * \version 1.6.0 The \p size parameter has changed from type \Code{hsize_t} to \Code{size_t}. + * + * \since 1.4.0 + */ +H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size); +/** + * \ingroup FAPL + * + * \brief Sets the size of a contiguous block reserved for small data + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of the small data block. + The default size is \Code{2048}. + * + * \return \herr_t + * + * \details H5Pset_small_data_block_size() reserves blocks of \p size bytes for the + * contiguous storage of the raw data portion of \Emph{small} datasets. The + * HDF5 library then writes the raw data from small datasets to this + * reserved space, thus reducing unnecessary discontinuities within + * blocks of meta data and improving I/O performance. + * + * A small data block is actually allocated the first time a qualifying + * small dataset is written to the file. Space for the raw data portion + * of this small dataset is suballocated within the small data block. + * The raw data from each subsequent small dataset is also written to + * the small data block until it is filled; additional small data + * blocks are allocated as required. + * + * The HDF5 library employs an algorithm that determines whether I/O + * performance is likely to benefit from the use of this mechanism with + * each dataset as storage space is allocated in the file. A larger + * \p size will result in this mechanism being employed with larger + * datasets. + * + * The small data block size is set as an allocation property in the + * file access property list identified by \p fapl_id. + * + * Setting \p size to zero (\Code{0}) disables the small data block mechanism. + * + * \since 1.4.4 + */ +H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size); /* Dataset creation property list (DCPL) routines */ -H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); +/** + * \ingroup DCPL + * + * \brief Determines whether fill value is defined + * + * \dcpl_id{plist} + * \param[out] status Status of fill value in property list + * + * \return \herr_t + * + * \details H5Pfill_value_defined() determines whether a fill value is + * defined in the dataset creation property list \p plist. Valid + * values returned in status are as follows: + * + * <table> + * <tr> + * <td>#H5D_FILL_VALUE_UNDEFINED</td> + * <td>Fill value is undefined.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_VALUE_DEFAULT</td> + * <td>Fill value is the library default.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_VALUE_USER_DEFINED</td> + * <td>Fill value is defined by the application.</td> + * </tr> + * </table> + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status); +/** + * \ingroup DCPL + * + * \brief Retrieves the timing for storage space allocation + * + * \dcpl_id{plist_id} + * \param[out] alloc_time The timing setting for allocating dataset + * storage space + * + * \return \herr_t + * + * \details H5Pget_alloc_time() retrieves the timing for allocating storage + * space for a dataset's raw data. This property is set in the + * dataset creation property list \p plist_id. The timing setting + * is returned in \p alloc_time as one of the following values: + * + * <table> + * <tr> + * <td>#H5D_ALLOC_TIME_DEFAULT<br /> </td> + * <td>Uses the default allocation time, based on the dataset + * storage method. <br />See the \p alloc_time description in + * H5Pset_alloc_time() for default allocation times for + * various storage methods.</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_EARLY</td> + * <td>All space is allocated when the dataset is created.</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_INCR</td> + * <td>Space is allocated incrementally as data is written + * to the dataset.</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_LATE</td> + * <td>All space is allocated when data is first written to + * the dataset.</td> + * </tr> + * </table> + * + * \note H5Pget_alloc_time() is designed to work in concert with the + * dataset fill value and fill value write time properties, set + * with the functions H5Pget_fill_value() and H5Pget_fill_time(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/); +/** + * \ingroup DCPL + * + * \brief Retrieves the size of chunks for the raw data of a chunked + * layout dataset + * + * \dcpl_id{plist_id} + * \param[in] max_ndims Size of the \p dims array + * \param[out] dim Array to store the chunk dimensions + * + * \return Returns chunk dimensionality if successful; + * otherwise returns a negative value. + * + * \details H5Pget_chunk() retrieves the size of chunks for the raw data + * of a chunked layout dataset. This function is only valid for + * dataset creation property lists. At most, \p max_ndims elements + * of \p dim will be initialized. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/); +/** + * \ingroup DCPL + * + * \brief Returns information about an external file + * + * \dcpl_id{plist_id} + * \param[in] idx External file index + * \param[in] name_size Maximum length of \p name array + * \param[out] name Name of the external file + * \param[out] offset Pointer to a location to return an offset value + * \param[out] size Pointer to a location to return the size of the + * external file data + * + * \return \herr_t + * + * \details H5Pget_external() returns information about an external file. + * The external file is specified by its index, \p idx, which + * is a number from zero to N-1, where N is the value returned + * by H5Pget_external_count(). At most \p name_size characters + * are copied into the \p name array. If the external file name + * is longer than \p name_size with the null terminator, the + * return value is not null terminated (similar to strncpy()). + * + * If \p name_size is zero or \p name is the null pointer, the + * external file name is not returned. If \p offset or \p size + * are null pointers then the corresponding information is not + * returned. + * + * \version 1.6.4 \p idx parameter type changed to unsigned. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/, + off_t *offset /*out*/, hsize_t *size /*out*/); +/** + * \ingroup DCPL + * + * \brief Returns the number of external files for a dataset + * + * \dcpl_id{plist_id} + * + * \return Returns the number of external files if successful; otherwise + * returns a negative value. + * + * \details H5Pget_external_count() returns the number of external files + * for the specified dataset. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Pget_external_count(hid_t plist_id); +/** + * \ingroup DCPL + * + * \brief Retrieves the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[out] fill_time Setting for the timing of writing fill values to + * the dataset + * + * \return \herr_t + * + * \details H5Pget_fill_time() examines the dataset creation property list + * \p plist_id to determine when fill values are to be written to + * a dataset. Valid values returned in \p fill_time are as + * follows: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Fill values are written to the dataset when storage + * space is allocated only if there is a user-defined fill + * value, i.e., one set with H5Pset_fill_value(). (Default) + * </td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Fill values are written to the dataset when storage + * space is allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Fill values are never written to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pget_fill_time() is designed to work in coordination with the + * dataset fill value and dataset storage allocation time properties, + * retrieved with the functions H5Pget_fill_value() and + * H5Pget_alloc_time(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/); +/** + * \ingroup DCPL + * + * \brief Retrieves a dataset fill value + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype identifier for the value passed via + * \p value + * \param[out] value Pointer to buffer to contain the returned + * fill value + * + * \return \herr_t + * + * \details H5Pget_fill_value() returns the dataset fill value defined in + * the dataset creation property list \p plist_id. The fill value + * is returned through the \p value pointer and will be converted + * to the datatype specified by \p type_id. This datatype may + * differ from the fill value datatype in the property list, but + * the HDF5 library must be able to convert between the two + * datatypes. + * + * If the fill value is undefined, i.e., set to NULL in the + * property list, H5Pget_fill_value() will return an error. + * H5Pfill_value_defined() should be used to check for this + * condition before H5Pget_fill_value() is called. + * + * Memory must be allocated by the calling application. + * + * \note H5Pget_fill_value() is designed to coordinate with the dataset + * storage allocation time and fill value write time properties, + * which can be retrieved with the functions H5Pget_alloc_time() + * and H5Pget_fill_time(), respectively. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/); +/** + * \ingroup DCPL + * + * \brief Returns the layout of the raw data for a dataset + * + * \dcpl_id{plist_id} + * + * \return Returns the layout type (a non-negative value) of a dataset + * creation property list if successful. Valid return values are: + * - #H5D_COMPACT: Raw data is stored in the object header in the + * file. + * - #H5D_CONTIGUOUS: Raw data is stored separately from the object + * header in one contiguous chunk in the file. + * - #H5D_CHUNKED: Raw data is stored separately from the object + * header in chunks in separate locations in the + * file. + * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in + * different files. + * \return + * Otherwise, returns a negative value indicating failure. + * + * \details H5Pget_layout() returns the layout of the raw data for a + * dataset. This function is only valid for dataset creation + * property lists. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the H5Dwrite() + * documentation for details. + * + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * + * \since 1.0.0 + * + */ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id); -H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); -H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/); -H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size); -H5_DLL int H5Pget_external_count(hid_t plist_id); -H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/, - off_t *offset /*out*/, hsize_t *size /*out*/); -H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); -H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); -H5_DLL herr_t H5Pset_nbit(hid_t plist_id); -H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor); -H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value); -H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/); -H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status); -H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time); -H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/); -H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); -H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/); +/** + * \ingroup DCPL + * + * \brief Sets the timing for storage space allocation + * + * \dcpl_id{plist_id} + * \param[in] alloc_time When to allocate dataset storage space + * + * \return \herr_t + * + * \details H5Pset_alloc_time() sets up the timing for the allocation of + * storage space for a dataset's raw data. This property is set + * in the dataset creation property list \p plist_id. Timing is + * specified in \p alloc_time with one of the following values: + * + * <table> + * <tr> + * <td>#H5D_ALLOC_TIME_DEFAULT</td> + * <td>Allocate dataset storage space at the default time<br /> + * (Defaults differ by storage method.)</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_EARLY</td> + * <td>Allocate all space when the dataset is created<br /> + * (Default for compact datasets.)</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_INCR</td> + * <td>Allocate space incrementally, as data is written to + * the dataset<br />(Default for chunked storage datasets.) + * + * \li Chunked datasets: Storage space allocation for each + * chunk is deferred until data is written to the chunk. + * \li Contiguous datasets: Incremental storage space + * allocation for contiguous data is treated as late + * allocation. + * \li Compact datasets: Incremental allocation is not + * allowed with compact datasets; H5Pset_alloc_time() + * will return an error.</td> + * </tr> + * <tr> + * <td>#H5D_ALLOC_TIME_LATE</td> + * <td>Allocate all space when data is first written to the + * dataset<br /> + * (Default for contiguous datasets.)</td> + * </tr> + * </table> + * + * \note H5Pset_alloc_time() is designed to work in concert with the + * dataset fill value and fill value write time properties, set + * with the functions H5Pset_fill_value() and H5Pset_fill_time(). + * + * \note See H5Dcreate() for further cross-references. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time); +/** + * \ingroup DCPL + * + * \brief Sets the size of the chunks used to store a chunked layout + * dataset + * + * \dcpl_id{plist_id} + * \param[in] ndims The number of dimensions of each chunk + * \param[in] dim An array defining the size, in dataset elements, of + * each chunk + * + * \return \herr_t + * \details H5Pset_chunk() sets the size of the chunks used to store a + * chunked layout dataset. This function is only valid for dataset + * creation property lists. + * + * The \p ndims parameter currently must be the same size as the + * rank of the dataset. + * + * The values of the \p dim array define the size of the chunks + * to store the dataset's raw data. The unit of measure for \p dim + * values is dataset elements. + * + * As a side-effect of this function, the layout of the dataset is + * changed to #H5D_CHUNKED, if it is not already so set. + * + * \note Chunk size cannot exceed the size of a fixed-size dataset. For + * example, a dataset consisting of a 5x4 fixed-size array cannot be + * defined with 10x10 chunks. Chunk maximums: + * - The maximum number of elements in a chunk is 2<sup>32</sup>-1 which + * is equal to 4,294,967,295. If the number of elements in a chunk is + * set via H5Pset_chunk() to a value greater than 2<sup>32</sup>-1, + * then H5Pset_chunk() will fail. + * - The maximum size for any chunk is 4GB. If a chunk that is larger + * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite() + * will fail. + * + * \see H5Pset_layout(), H5Dwrite() + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); +/** + * \ingroup DCPL + * + * \brief Adds an external file to the list of external files + * + * \dcpl_id{plist_id} + * \param[in] name Name of an external file + * \param[in] offset Offset, in bytes, from the beginning of the file to + * the location in the file where the data starts + * \param[in] size Number of bytes reserved in the file for the data + * + * \return \herr_t + * + * \details The first call to H5Pset_external() sets the external + * storage property in the property list, thus designating that + * the dataset will be stored in one or more non-HDF5 file(s) + * external to the HDF5 file. This call also adds the file + * \p name as the first file in the list of external files. + * Subsequent calls to the function add the named file as the + * next file in the list. + * + * If a dataset is split across multiple files, then the files + * should be defined in order. The total size of the dataset is + * the sum of the \p size arguments for all the external files. + * If the total size is larger than the size of a dataset then + * the dataset can be extended (provided the data space also + * allows the extending). + * + * The \p size argument specifies the number of bytes reserved + * for data in the external file. If \p size is set to + * #H5F_UNLIMITED, the external file can be of unlimited size + * and no more files can be added to the external files list. + * If \p size is set to 0 (zero), no external file will actually + * be created. + * + * All of the external files for a given dataset must be specified + * with H5Pset_external() before H5Dcreate() is called to create + * the dataset. If one these files does not exist on the system + * when H5Dwrite() is called to write data to it, the library + * will create the file. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size); +/** + * \ingroup DCPL + * + * \brief Sets the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[in] fill_time When to write fill values to a dataset + * + * \return \herr_t + * + * \details H5Pset_fill_time() sets up the timing for writing fill values + * to a dataset. This property is set in the dataset creation + * property list \p plist_id. Timing is specified in \p fill_time + * with one of the following values: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Write fill values to the dataset when storage space is + * allocated only if there is a user-defined fill value, + * i.e.,one set with H5Pset_fill_value(). (Default)</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Write fill values to the dataset when storage space is + * allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Never write fill values to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pset_fill_time() is designed for coordination with the dataset + * fill value and dataset storage allocation time properties, set + * with the functions H5Pset_fill_value() and H5Pset_alloc_time(). + * See H5Dcreate() for further cross-references. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); +/** + * \ingroup DCPL + * + * \brief Sets the fill value for a dataset + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype of \p value + * \param[in] value Pointer to buffer containing value to use as + * fill value + * + * \return \herr_t + * + * \details H5Pset_fill_value() sets the fill value for a dataset in the + * dataset creation property list. \p value is interpreted as + * being of datatype \p type_id. This datatype may differ from + * that of the dataset, but the HDF5 library must be able to + * convert \p value to the dataset datatype when the dataset is + * created. + * + * The default fill value is 0 (zero), which is interpreted + * according to the actual dataset datatype. + * + * Setting \p value to NULL indicates that the fill value is to + * be undefined. + * + * \note Applications sometimes write data only to portions of an allocated + * dataset. It is often useful in such cases to fill the unused space + * with a known fill value. This function allows the user application + * to set that fill value; the functions H5Dfill() and + * H5Pset_fill_time(), respectively, provide the ability to apply the + * fill value on demand or to set up its automatic application. + * + * \note A fill value should be defined so that it is appropriate for the + * application. While the HDF5 default fill value is 0 (zero), it is + * often appropriate to use another value. It might be useful, for + * example, to use a value that is known to be impossible for the + * application to legitimately generate. + * + * \note H5Pset_fill_value() is designed to work in concert with + * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time() + * and H5Pset_fill_time() govern the timing of dataset storage + * allocation and fill value write operations and can be important in + * tuning application performance. + * + * \note See H5Dcreate() for further cross-references. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value); +/** + * \ingroup DCPL + * + * \brief Sets up use of the shuffle filter + * + * \dcpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, + * in the dataset creation property list \p plist_id. The shuffle + * filter de-interlaces a block of data by reordering the bytes. + * All the bytes from one consistent byte position of each data + * element are placed together in one block; all bytes from a + * second consistent byte position of each data element are placed + * together a second block; etc. For example, given three data + * elements of a 4-byte datatype stored as 012301230123, shuffling + * will re-order data as 000111222333. This can be a valuable step + * in an effective compression algorithm because the bytes in each + * byte position are often closely related to each other and + * putting them together can increase the compression ratio. + * + * As implied above, the primary value of the shuffle filter lies + * in its coordinated use with a compression filter; it does not + * provide data compression when used alone. When the shuffle + * filter is applied to a dataset immediately prior to the use of + * a compression filter, the compression ratio achieved is often + * superior to that achieved by the use of a compression filter + * without the shuffle filter. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); +/** + * \ingroup DCPL + * + * \brief Sets the type of storage used to store the raw data for a dataset + * + * \dcpl_id{plist_id} + * \param[in] layout Type of storage layout for raw data + * + * \return \herr_t + * \details H5Pset_layout() sets the type of storage used to store the raw + * data for a dataset. This function is only valid for dataset + * creation property lists. + * + * Valid values for \p layout are: + * - #H5D_COMPACT: Store raw data in the dataset object header + * in file. This should only be used for datasets + * with small amounts of raw data. The raw data + * size limit is 64K (65520 bytes). Attempting + * to create a dataset with raw data larger than + * this limit will cause the H5Dcreate() call to + * fail. + * - #H5D_CONTIGUOUS: Store raw data separately from the object + * header in one large chunk in the file. + * - #H5D_CHUNKED: Store raw data separately from the object header + * as chunks of data in separate locations in + * the file. + * - #H5D_VIRTUAL: Draw raw data from multiple datasets in + * different files. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the note in + * H5Dwrite() documentation for details. + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); +/** + * \ingroup DCPL + * + * \brief Sets up the use of the N-Bit filter + * + * \dcpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the + * dataset creation property list \p plist_id. + * + * The HDF5 user can create an N-Bit datatype with the following + * code: + * <pre> + * hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE); + * H5Tset_precision(nbit_datatype, 16); + * H5Tset_offset(nbit_datatype, 4); + * </pre> + * + * In memory, one value of the N-Bit datatype in the above example + * will be stored on a little-endian machine as follows: + * + * <table> + * <tr> + * <td>byte 3</td> + * <td>byte 2</td> + * <td>byte 1</td> + * <td>byte 0</td> + * </tr> + * <tr> + * <td>????????</td> + * <td>????SPPP</td> + * <td>PPPPPPPP</td> + * <td>PPPP????</td> + * </tr> + * </table> + * Note: S - sign bit, P - significant bit, ? - padding bit; For + * signed integer, the sign bit is included in the precision. + * + * When data of the above datatype is stored on disk using the + * N-bit filter, all padding bits are chopped off and only + * significant bits are stored. The values on disk will be + * something like: + * + * <table> + * <tr> + * <td>1st value</td> + * <td>2nd value</td> + * <td>...</td> + * </tr> + * <tr> + * <td>SPPPPPPPPPPPPPPP</td> + * <td>SPPPPPPPPPPPPPPP</td> + * <td>...</td> + * </tr> + * </table> + * The N-Bit filter is used effectively for compressing data of + * an N-Bit datatype as well as a compound and an array + * datatype with N-Bit fields. However, the datatype classes of + * the N-Bit datatype or the N-Bit field of the compound + * datatype or the array datatype are limited to integer or + * floating-point. + * + * The N-Bit filter supports complex situations where a compound + * datatype contains member(s) of a compound datatype or an array + * datatype that has a compound datatype as the base type. + * However, it does not support the situation where an array + * datatype has a variable-length or variable-length string as + * its base datatype. The filter does support the situation where + * a variable-length or variable-length string is a member of a + * compound datatype. + * + * The N-Bit filter allows all other HDF5 datatypes (such as + * time, string, bitfield, opaque, reference, enum, and variable + * length) to pass through as a no-op. + * + * Like other I/O filters supported by the HDF5 library, + * application using the N-Bit filter must store data with + * chunked storage. + * + * By nature, the N-Bit filter should not be used together with + * other I/O filters. + * + * \version 1.8.8 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_nbit(hid_t plist_id); +/** + * \ingroup DCPL + * + * \brief Sets up the use of the scale-offset filter + * + * \dcpl_id{plist_id} + * \param[in] scale_type Flag indicating compression method + * \param[in] scale_factor Parameter related to scale. Must be + * non-negative + * + * \return \herr_t + * + * \details H5Pset_scaleoffset() sets the scale-offset filter, + * #H5Z_FILTER_SCALEOFFSET, for a dataset. + * + * Generally speaking, scale-offset compression performs a scale and/or + * offset operation on each data value and truncates the resulting + * value to a minimum number of bits (MinBits) before storing it. The + * current scale-offset filter supports integer and floating-point + * datatypes. + * + * For an integer datatype, the parameter \p scale_type should be set + * to #H5Z_SO_INT (2). The parameter \p scale_factor denotes MinBits. + * If the user sets it to H5Z_SO_INT_MINBITS_DEFAULT (0), the filter + * will calculate MinBits. If \p scale_factor is set to a positive + * integer, the filter does not do any calculation and just uses the + * number as MinBits. However, if the user gives a MinBits that is less + * than what would be generated by the filter, the compression will be + * lossy. Also, the MinBits supplied by the user cannot exceed the + * number of bits to store one value of the dataset datatype. + * + * For a floating-point datatype, the filter adopts the GRiB data + * packing mechanism, which offers two alternate methods: E-scaling and + * D-scaling. Both methods are lossy compression. If the parameter + * \p scale_type is set to #H5Z_SO_FLOAT_DSCALE (0), the filter will + * use the D-scaling method; if it is set to #H5Z_SO_FLOAT_ESCALE (1), + * the filter will use the E-scaling method. Since only the D-scaling + * method is implemented, \p scale_type should be set to + * #H5Z_SO_FLOAT_DSCALE or 0. + * + * When the D-scaling method is used, the original data is "D" scaled + * — multiplied by 10 to the power of \p scale_factor, and the + * "significant" part of the value is moved to the left of the decimal + * point. Care should be taken in setting the decimal \p scale_factor + * so that the integer part will have enough precision to contain the + * appropriate information of the data value. For example, if + * \p scale_factor is set to 2, the number 104.561 will be 10456.1 + * after "D" scaling. The last digit 1 is not "significant" and is + * thrown off in the process of rounding. The user should make sure that + * after "D" scaling and rounding, the data values are within the range + * that can be represented by the integer (same size as the + * floating-point type). + * + * Valid values for scale_type are as follows: + * + * <table> + * <tr> + * <td>#H5Z_SO_FLOAT_DSCALE (0)</td> + * <td>Floating-point type, using variable MinBits method</td> + * </tr> + * <tr> + * <td>#H5Z_SO_FLOAT_ESCALE (1)</td> + * <td>Floating-point type, using fixed MinBits method</td> + * </tr> + * <tr> + * <td>#H5Z_SO_INT (2)</td> + * <td>Integer type</td> + * </tr> + * </table> + * + * The meaning of \p scale_factor varies according to the value + * assigned to \p scale_type: + * + * <table> + * <tr> + * <th>\p scale_type value</th> + * <th>\p scale_factor description</th> + * </tr> + * <tr> + * <td>#H5Z_SO_FLOAT_DSCALE</td> + * <td>Denotes the decimal scale factor for D-scaling and can be + * positive, negative or zero. This is the current + * implementation of the library.</td> + * </tr> + * <tr> + * <td>#H5Z_SO_FLOAT_ESCALE</td> + * <td>Denotes MinBits for E-scaling and must be a positive integer. + * This is not currently implemented by the library.</td> + * </tr> + * <tr> + * <td>#H5Z_SO_INT</td> + * <td>Denotes MinBits and it should be a positive integer or + * #H5Z_SO_INT_MINBITS_DEFAULT (0). If it is less than 0, the + * library will reset it to 0 since it is not implemented. + * </td> + * </tr> + * </table> + * Like other I/O filters supported by the HDF5 library, an + * application using the scale-offset filter must store data with + * chunked storage. + * + * \version 1.8.8 Fortran90 subroutine introduced in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor); +/** + * \ingroup DCPL + * + * \brief Sets up use of the SZIP compression filter + * + * \dcpl_id{plist_id} + * \param[in] options_mask A bit-mask conveying the desired SZIP options; + * Valid values are #H5_SZIP_EC_OPTION_MASK and + * #H5_SZIP_NN_OPTION_MASK. + * \param[in] pixels_per_block The number of pixels or data elements in each + * data block + * + * \return \herr_t + * + * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, + * for a dataset. SZIP is a compression method designed for use with + * scientific data. + * + * Before proceeding, all users should review the “Limitations” + * section below. + * + * Users familiar with SZIP outside the HDF5 context may benefit + * from reviewing the Note “For Users Familiar with SZIP in Other + * Contexts” below. + * + * In the text below, the term pixel refers to an HDF5 data element. + * This terminology derives from SZIP compression's use with image + * data, where pixel referred to an image pixel. + * + * The SZIP \p bits_per_pixel value (see Note, below) is automatically + * set, based on the HDF5 datatype. SZIP can be used with atomic + * datatypes that may have size of 8, 16, 32, or 64 bits. + * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or + * 64-bit signed or unsigned integer; char; or 32- or 64-bit float + * can be compressed with SZIP. See Note, below, for further + * discussion of the the SZIP \p bits_per_pixel setting. + * + * SZIP options are passed in an options mask, \p options_mask, + * as follows. + * + * <table> + * <tr> + * <th>Option</th> + * <th>Description (Mutually exclusive; select one.)</th> + * </tr> + * <tr> + * <td>#H5_SZIP_EC_OPTION_MASK</td> + * <td>Selects entropy coding method</td> + * </tr> + * <tr> + * <td>#H5_SZIP_NN_OPTION_MASK</td> + * <td>Selects nearest neighbor coding method</td> + * </tr> + * </table> + * + * The following guidelines can be used in determining which + * option to select: + * + * - The entropy coding method, the EC option specified by + * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been + * processed. The EC method works best for small numbers. + * - The nearest neighbor coding method, the NN option specified + * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the + * applies EC method as above. + * + * Other factors may affect results, but the above criteria + * provides a good starting point for optimizing data compression. + * + * SZIP compresses data block by block, with a user-tunable block + * size. This block size is passed in the parameter + * \p pixels_per_block and must be even and not greater than 32, + * with typical values being 8, 10, 16, or 32. This parameter + * affects compression ratio; the more pixel values vary, the + * smaller this number should be to achieve better performance. + * + * In HDF5, compression can be applied only to chunked datasets. + * If \p pixels_per_block is bigger than the total number of + * elements in a dataset chunk, H5Pset_szip() will succeed but + * the subsequent call to H5Dcreate() will fail; the conflict + * can be detected only when the property list is used. + * + * To achieve optimal performance for SZIP compression, it is + * recommended that a chunk's fastest-changing dimension be equal + * to N times \p pixels_per_block where N is the maximum number of + * blocks per scan line allowed by the SZIP library. In the + * current version of SZIP, N is set to 128. + * + * SZIP compression is an optional HDF5 filter. + * + * \b Limitations: + * + * - SZIP compression cannot be applied to compound, array, + * variable-length, enumeration, or any other user-defined + * datatypes. If an SZIP filter is set in a dataset creation + * property list used to create a dataset containing a + * non-allowed datatype, the call to H5Dcreate() will fail; the + * conflict can be detected only when the property list is used. + * - Users should be aware that there are factors that affect one’s + * rights and ability to use SZIP compression by reviewing the + * SZIP copyright notice. + * + * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts: + * + * \note The following notes are of interest primarily to those who have + * used SZIP compression outside of the HDF5 context. + * In non-HDF5 applications, SZIP typically requires that the user + * application supply additional parameters: + * - \p pixels_in_object, the number of pixels in the object to + * be compressed + * - \p bits_per_pixel, the number of bits per pixel + * - \p pixels_per_scanline, the number of pixels per scan line + * + * \note These values need not be independently supplied in the HDF5 + * environment as they are derived from the datatype and dataspace, + * which are already known. In particular, HDF5 sets + * \p pixels_in_object to the number of elements in a chunk and + * \p bits_per_pixel to the size of the element or pixel datatype. + * + * \note The following algorithm is used to set \p pixels_per_scanline: + * - If the size of a chunk's fastest-changing dimension, size, + * is greater than 4K, set \p pixels_per_scanline to 128 times + * \p pixels_per_block. + * - If size is less than 4K but greater than \p pixels_per_block, + * set \p pixels_per_scanline to the minimum of size and 128 + * times \p pixels_per_block. + * - If size is less than \p pixels_per_block but greater than the + * number elements in the chunk, set \p pixels_per_scanline to + * the minimum of the number elements in the chunk and 128 times + * \p pixels_per_block. + * + * \note The HDF5 datatype may have precision that is less than the full + * size of the data element, e.g., an 11-bit integer can be defined + * using H5Tset_precision(). To a certain extent, SZIP can take + * advantage of the precision of the datatype to improve compression: + * - If the HDF5 datatype size is 24-bit or less and the offset of + * the bits in the HDF5 datatype is zero (see H5Tset_offset() or + * H5Tget_offset()), the data is the in lowest N bits of the data + * element. In this case, the SZIP \p bits_per_pixel is set to the + * precision of the HDF5 datatype. + * - If the offset is not zero, the SZIP \p bits_per_pixel will be + * set to the number of bits in the full size of the data element. + * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP + * \p bits_per_pixel will be set to 32. + * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP + * \p bits_per_pixel will be set to 64. + * + * \note HDF5 always modifies the options mask provided by the user to set up + * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of + * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the + * datatype. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); /* Dataset access property list (DAPL) routines */ -H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0); -H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, - double *rdcc_w0 /*out*/); -H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char *prefix); +/** + * \ingroup DAPL + * + * \brief Retrieves the raw data chunk cache parameters + * + * \dapl_id + * \param[out] rdcc_nslots Number of chunk slots in the raw data chunk + * cache hash table + * \param[out] rdcc_nbytes Total size of the raw data chunk cache, in + * bytes + * \param[out] rdcc_w0 Preemption policy + * + * \return \herr_t + * + * \details H5Pget_chunk_cache() retrieves the number of chunk slots in + * the raw data chunk cache hash table, the maximum possible + * number of bytes in the raw data chunk cache, and the + * preemption policy value. + * + * These values are retrieved from a dataset access property + * list. If the values have not been set on the property list, + * then values returned will be the corresponding values from + * a default file access property list. + * + * Any (or all) pointer arguments may be null pointers, in which + * case the corresponding data is not returned. + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, + double *rdcc_w0 /*out*/); +/** + * \ingroup DAPL + * + * \brief Retrieves the prefix for external raw data storage files as set + * in the dataset access property list + * + * \dapl_id + * \param[in,out] prefix Dataset external storage prefix in UTF-8 or + * ASCII (\em Path and \em filename must be ASCII + * on Windows systems.) + * \param[in] size Size of prefix buffer in bytes + * + * \return Returns the size of \p prefix and the prefix string will be + * stored in \p prefix if successful. + * Otherwise returns a negative value and the contents of \p prefix + * will be undefined. + * + * \details H5Pget_efile_prefix() retrieves the file system path prefix + * for locating external files associated with a dataset that + * uses external storage. This will be the value set with + * H5Pset_efile_prefix() or the HDF5 library’s default. + * + * The value of \p size is the size in bytes of the prefix, + * including the NULL terminator. If the size is unknown, a + * preliminary H5Pget_elink_prefix() call with the pointer + * \p prefix set to NULL will return the size of the prefix + * without the NULL terminator. + * + * The \p prefix buffer must be allocated by the caller. In a + * call that retrieves the actual prefix, that buffer must be + * of the size specified in \p size. + * + * \note See H5Pset_efile_prefix() for a more complete description of + * file location behavior and for notes on the use of the + * HDF5_EXTFILE_PREFIX environment variable. + * + * \since 1.10.0, 1.8.17 + * + */ H5_DLL ssize_t H5Pget_efile_prefix(hid_t dapl_id, char *prefix /*out*/, size_t size); +/** + * \ingroup DAPL + * + * \brief Sets the raw data chunk cache parameters + * + * \dapl_id + * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk + * cache for this dataset. Increasing this value + * reduces the number of cache collisions, but + * slightly increases the memory used. Due to the + * hashing strategy, this value should ideally be a + * prime number. As a rule of thumb, this value + * should be at least 10 times the number of chunks + * that can fit in \p rdcc_nbytes bytes. For maximum + * performance, this value should be set + * approximately 100 times that number of chunks. + * The default value is 521. If the value passed is + * #H5D_CHUNK_CACHE_NSLOTS_DEFAULT, then the + * property will not be set on \p dapl_id and the + * parameter will come from the file access + * property list used to open the file. + * \param[in] rdcc_nbytes The total size of the raw data chunk cache for + * this dataset. In most cases increasing this + * number will improve performance, as long as + * you have enough free memory. + * The default size is 1 MB. If the value passed is + * #H5D_CHUNK_CACHE_NBYTES_DEFAULT, then the + * property will not be set on \p dapl_id and the + * parameter will come from the file access + * property list. + * \param[in] rdcc_w0 The chunk preemption policy for this dataset. + * This must be between 0 and 1 inclusive and + * indicates the weighting according to which chunks + * which have been fully read or written are + * penalized when determining which chunks to flush + * from cache. A value of 0 means fully read or + * written chunks are treated no differently than + * other chunks (the preemption is strictly LRU) + * while a value of 1 means fully read or written + * chunks are always preempted before other chunks. + * If your application only reads or writes data + * once, this can be safely set to 1. Otherwise, + * this should be set lower, depending on how often + * you re-read or re-write the same data. + * The default value is 0.75. If the value passed is + * #H5D_CHUNK_CACHE_W0_DEFAULT, then the property + * will not be set on \p dapl_id and the parameter + * will come from the file access property list. + * + * \return \herr_t + * + * \details H5Pset_chunk_cache() sets the number of elements, the total + * number of bytes, and the preemption policy value in the raw + * data chunk cache on a dataset access property list. After + * calling this function, the values set in the property list + * will override the values in the file's file access property + * list. + * + * The raw data chunk cache inserts chunks into the cache + * by first computing a hash value using the address of a chunk, + * then using that hash value as the chunk's index into the table + * of cached chunks. The size of this hash table, i.e., and the + * number of possible hash values, is determined by the + * \p rdcc_nslots parameter. If a different chunk in the cache + * has the same hash value, this causes a collision, which + * reduces efficiency. If inserting the chunk into cache would + * cause the cache to be too big, then the cache is pruned + * according to the \p rdcc_w0 parameter. + * + * \b Motivation: H5Pset_chunk_cache() is used to adjust the chunk + * cache parameters on a per-dataset basis, as opposed to a global + * setting for the file using H5Pset_cache(). The optimum chunk + * cache parameters may vary widely with different data layout and + * access patterns, so for optimal performance they must be set + * individually for each dataset. It may also be beneficial to + * reduce the size of the chunk cache for datasets whose + * performance is not important in order to save memory space. + * + * \b Example \b Usage: The following code sets the chunk cache to + * use a hash table with 12421 elements and a maximum size of + * 16 MB, while using the preemption policy specified for the + * entire file: + * \Code{ + * H5Pset_chunk_cache(dapl_id, 12421, 16*1024*1024, + * H5D_CHUNK_CACHE_W0_DEFAULT);} + * + * \b Usage \b Notes: The chunk cache size is a property for + * accessing a dataset and is not stored with a dataset or a + * file. To guarantee the same chunk cache settings each time + * the dataset is opened, call H5Dopen() with a dataset access + * property list where the chunk cache size is set by calling + * H5Pset_chunk_cache() for that property list. The property + * list can be used for multiple accesses in the same + * application. + * + * For files where the same chunk cache size will be + * appropriate for all or most datasets, H5Pset_cache() can + * be called with a file access property list to set the + * chunk cache size for accessing all datasets in the file. + * + * Both methods can be used in combination, in which case + * the chunk cache size set by H5Pset_cache() will apply + * except for specific datasets where H5Dopen() is called + * with dataset property list with the chunk cache size + * set by H5Pset_chunk_cache(). + * + * In the absence of any cache settings, H5Dopen() will + * by default create a 1 MB chunk cache for the opened + * dataset. If this size happens to be appropriate, no + * call will be needed to either function to set the + * chunk cache size. + * + * It is also possible that a change in access pattern + * for later access to a dataset will change the + * appropriate chunk cache size. + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0); +/** + * \ingroup DAPL + * + * \brief Sets the external dataset storage file prefix in the dataset + * access property list + * + * \dapl_id + * \param[in] prefix Dataset external storage prefix in UTF-8 or ASCII + * (<em>Path and filename must be ASCII on Windows systems.</em>) + * + * \return \herr_t + * + * \details H5Pset_efile_prefix() sets the prefix used to locate raw data + * files for a dataset that uses external storage. This prefix + * can provide either an absolute path or a relative path to the + * external files. + * + * H5Pset_efile_prefix() is used in conjunction with + * H5Pset_external() to control the behavior of the HDF5 library + * when searching for the raw data files associated with a dataset + * that uses external storage: + * + * \li The default behavior of the library is to search for the + * dataset’s external storage raw data files in the same + * directory as the HDF5 file which contains the dataset. + * \li If the prefix is set to an absolute path, the target + * directory will be searched for the dataset’s external + * storage raw data files. + * \li If the prefix is set to a relative path, the target + * directory, relative to the current working directory, will + * be searched for the dataset’s external storage raw data + * files. + * \li If the prefix is set to a relative path that begins with + * the special token ${ORIGIN}, that directory, relative to + * the HDF5 file containing the dataset, will be searched for + * the dataset’s external storage raw data files. + * + * The HDF5_EXTFILE_PREFIX environment variable can be used to + * override the above behavior (the environment variable + * supersedes the API call). Setting the variable to a path + * string and calling H5Dcreate() or H5Dopen() is the equivalent + * of calling H5Pset_efile_prefix() and calling the same create + * or open function. The environment variable is checked at the + * time of the create or open action and copied so it can be + * safely changed after the H5Dcreate() or H5Dopen() call. + * + * Calling H5Pset_efile_prefix() with \p prefix set to NULL or + * the empty string returns the search path to the default. The + * result would be the same as if H5Pset_efile_prefix() had never + * been called. + * + * \note If the external file prefix is not an absolute path and the HDF5 + * file is moved, the external storage files will also need to be + * moved so they can be accessed at the new location. + * + * \note As stated above, the use of the HDF5_EXTFILE_PREFIX environment + * variable overrides any property list setting. + * H5Pset_efile_prefix() and H5Pget_efile_prefix(), being property + * functions, set and retrieve only the property list setting; they + * are unaware of the environment variable. + * + * \note On Windows, the prefix must be an ASCII string since the Windows + * standard C library’s I/O functions cannot handle UTF-8 file names. + * + * \since 1.10.0, 1.8.17 + * + */ +H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char *prefix); /* Dataset xfer property list (DXPL) routines */ -H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char *expression); -H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size); -H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg); -H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*out*/); -H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); -H5_DLL int H5Pget_preserve(hid_t plist_id); -H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check); +/** + * + * \ingroup DXPL + * + * \brief Gets B-tree split ratios for a dataset transfer property list + * + * \dxpl_id{plist_id} + * \param[out] left The B-tree split ratio for left-most nodes + * \param[out] middle The B-tree split ratio for right-most nodes and lone nodes + * \param[out] right The B-tree split ratio for all other nodes + * \return \herr_t + * + * \details H5Pget_btree_ratios() returns the B-tree split ratios for a dataset + * transfer property list. + * + * The B-tree split ratios are returned through the non-NULL arguments + * \p left, \p middle, and \p right, as set by the H5Pset_btree_ratios() + * function. + * + */ +H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left /*out*/, double *middle /*out*/, + double *right /*out*/); +/** + * + * \ingroup DXPL + * + * \brief Reads buffer settings + * + * \param[in] plist_id Identifier for the dataset transfer property list + * \param[out] tconv Address of the pointer to application-allocated type + * conversion buffer + * \param[out] bkg Address of the pointer to application-allocated + * background buffer + * + * \return Returns buffer size, in bytes, if successful; otherwise 0 on failure. + * + * \details H5Pget_buffer() reads values previously set with H5Pset_buffer(). + * + * \version 1.6.0 The return type changed from \p hsize_t to \p size_t. + * \version 1.4.0 The return type changed to \p hsize_t. + * + */ +H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*out*/); +/** + * + * \ingroup DXPL + * + * \brief Retrieves a data transform expression + * + * \param[in] plist_id Identifier of the property list or class + * \param[out] expression Pointer to memory where the transform expression will + * be copied + * \param[in] size Number of bytes of the transform expression to copy + * to + * + * \return Success: the size of the transform expression. Failure: a negative + * value. + * + * \details H5Pget_data_transform() retrieves the data transform expression + * previously set in the dataset transfer property list \p plist_id + * by H5Pset_data_transform(). + * + * H5Pget_data_transform() can be used to both retrieve the transform + * expression and query its size. + * + * If \p expression is non-NULL, up to \p size bytes of the data + * transform expression are written to the buffer. If \p expression + * is NULL, \p size is ignored, and the function does not write + * anything to the buffer. The function always returns the size of + * the data transform expression. + * + * If 0 is returned for the size of the expression, no data transform + * expression exists for the property list. + * + * If an error occurs, the buffer pointed to by \p expression is + * unchanged, and the function returns a negative value. + * + * \par Example + * An example snippet from examples/h5_dtransform.c: + * \snippet h5_dtransform.c H5Pget_data_transform_snip + * + * \since 1.8.0 + * + */ +H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size); +/** + * + * \ingroup DXPL + * + * \brief Determines whether error-detection is enabled for dataset reads + * + * \param[in] plist_id Dataset transfer property list identifier + * + * \return Returns \p H5Z_ENABLE_EDC or \p H5Z_DISABLE_EDC if successful; + * otherwise returns a negative value. + * + * \details H5Pget_edc_check() queries the dataset transfer property + * list \p plist to determine whether error detection is enabled for + * data read operations. + * + * \since 1.6.0 + * + */ H5_DLL H5Z_EDC_t H5Pget_edc_check(hid_t plist_id); -H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void *op_data); -H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right); -H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left /*out*/, double *middle /*out*/, - double *right /*out*/); -H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, - H5MM_free_t free_func, void *free_info); -H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, - H5MM_free_t *free_func, void **free_info); -H5_DLL herr_t H5Pset_hyper_vector_size(hid_t fapl_id, size_t size); -H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); -H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); -H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); +/** + * + * \ingroup DXPL + * + * \brief Retrieves number of I/O vectors to be read/written in hyperslab I/O + * + * \param[in] fapl_id Dataset transfer property list identifier + * \param[out] size Number of I/O vectors to accumulate in memory for I/O operations + * + * \return \herr_t + * + * \details H5Pget_hyper_vector_size() retrieves the number of I/O vectors to be accumulated in + * memory before being issued to the lower levels of the HDF5 library for reading or + * writing the actual data. + * + * The number of I/O vectors set in the dataset transfer property list \p fapl_id is + * returned in \p size. Unless the default value is in use, \p size was + * previously set with a call to H5Pset_hyper_vector_size(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); +/** + * + * \ingroup DXPL + * + * \brief Checks status of the dataset transfer property list (\b DEPRECATED) + * + * \deprecated{H5Pget_preserve() is deprecated as it is no longer useful; + * compound datatype field preservation is now core functionality + * in the HDF5 library.} + * + * \param[in] plist_id Identifier for the dataset transfer property list + * + * \return Returns 1 or 0 if successful; otherwise returns a negative value. + * + * \details H5Pget_preserve() checks the status of the dataset transfer + * property list. + * + * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to + * better match the C API. (Fortran 90) + * + */ +H5_DLL int H5Pget_preserve(hid_t plist_id); +/** + * + * \ingroup DXPL + * + * \brief Gets user-defined datatype conversion callback function + * + * \param[in] dxpl_id Dataset transfer property list identifier + * \param[out] op User-defined type conversion callback function + * \param[out] operate_data User-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pget_type_conv_cb() gets the user-defined datatype conversion + * callback function \p op in the dataset transfer property list + * \p dxpl_id. + * + * The parameter \p operate_data is a pointer to user-defined input + * data for the callback function. + * + * The callback function \p op defines the actions an application is + * to take when there is an exception during datatype conversion. + * + * Please refer to the function H5Pset_type_conv_cb() for more details. + * + */ +H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); +/** + * + * \ingroup DXPL + * + * \brief Gets the memory manager for variable-length datatype allocation in H5Dread() and H5Dvlen_reclaim() + * + * \param[in] plist_id Identifier for the dataset transfer property list + * \param[out] alloc_func User's allocate routine, or NULL for system malloc + * \param[out] alloc_info Extra parameter for user’s allocation routine. + * Contents are ignored if preceding + * parameter is NULL \param[out] free_func User's free routine, or NULL for + * system free \param[out] free_info + * Extra parameter for user’s free routine. Contents are ignored if preceding + * parameter is NULL + * + * \return \herr_t + * + * \details H5Pget_vlen_mem_manager() is the companion function to + * H5Pset_vlen_mem_manager(), returning the parameters set by + * that function. + * + */ +H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, + H5MM_free_t *free_func, void **free_info); +/** + * + * \ingroup DXPL + * + * \brief Sets B-tree split ratios for a dataset transfer property list + * + * \param[in] plist_id The dataset transfer property list identifier + * \param[in] left The B-tree split ratio for left-most nodes + * \param[in] middle The B-tree split ratio for all other nodes + * \param[in] right The B-tree split ratio for right-most nodes and lone + * nodes + * + * \return \herr_t + * + * \details H5Pset_btree_ratios() sets the B-tree split ratios for a dataset + * transfer property list. The split ratios determine what percent of + * children go in the first node when a node splits. + * + * The ratio \p left is used when the splitting node is the left-most + * node at its level in the tree; + * the ratio \p right is used when the splitting node is the right-most + * node at its level; and + * the ratio \p middle is used for all other cases. + * + * A node that is the only node at its level in the tree uses the + * ratio \p right when it splits. + * + * All ratios are real numbers between 0 and 1, inclusive. + * + */ +H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right); + +/** + * + * \ingroup DXPL + * + * \brief Sets type conversion and background buffers + * + * \dxpl_id{plist_id} + * \param[in] size Size, in bytes, of the type conversion and background buffers + * \param[in] tconv Pointer to application-allocated type conversion buffer + * \param[in] bkg Pointer to application-allocated background buffer + * \return \herr_t + * + * \details Given a dataset transfer property list, H5Pset_buffer() sets the + * maximum size for the type conversion buffer and background buffer + * and optionally supplies pointers to application-allocated + * buffers. If the buffer size is smaller than the entire amount of + * data being transferred between the application and the file, and a + * type conversion buffer or background buffer is required, then strip + * mining will be used. + * + * Note that there are minimum size requirements for the buffer. Strip + * mining can only break the data up along the first dimension, so the + * buffer must be large enough to accommodate a complete slice that + * encompasses all of the remaining dimensions. For example, when strip + * mining a \Code{100x200x300} hyperslab of a simple data space, the + * buffer must be large enough to hold \Code{1x200x300} data + * elements. When strip mining a \Code{100x200x300x150} hyperslab of a + * simple data space, the buffer must be large enough to hold + * \Code{1x200x300x150} data elements. + * + * If \p tconv and/or \p bkg are null pointers, then buffers will be + * allocated and freed during the data transfer. + * + * The default value for the maximum buffer is 1 MiB. + * + * \version 1.6.0 The \p size parameter has changed from type hsize_t to \c size_t. + * \version 1.4.0 The \p size parameter has changed to type hsize_t. + * + */ +H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg); + +/** + * \ingroup DXPL + * + * \brief Sets a data transform expression + * + * \dxpl_id{plist_id} + * \param[in] expression Pointer to the null-terminated data transform + * expression + * \return \herr_t + * + * \details H5Pset_data_transform() sets the data transform to be used for + * reading and writing data. This function operates on the dataset + * transfer property list \p plist_id. + * + * The \p expression parameter is a string containing an algebraic + * expression, such as \Code{(5/9.0)*(x-32)} or \Code{x*(x-5)}. When a + * dataset is read or written with this property list, the transform + * expression is applied with the \c x being replaced by the values in + * the dataset. When reading data, the values in the file are not + * changed and the transformed data is returned to the user. + * + * Data transforms can only be applied to integer or + * floating-point datasets. Order of operations is obeyed and + * the only supported operations are +, -, *, and /. Parentheses + * can be nested arbitrarily and can be used to change precedence. + * When writing data back to the dataset, the transformed data is + * written to the file and there is no way to recover the original + * values to which the transform was applied. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char *expression); + +/** + * \ingroup DXPL + * + * \brief Sets the dataset transfer property list to enable or disable error + * detection when reading data + * + * \dxpl_id{plist_id} + * \param[in] check Specifies whether error checking is enabled or disabled + * for dataset read operations + * \return \herr_t + * + * \details H5Pset_edc_check() sets the dataset transfer property list \p plist + * to enable or disable error detection when reading data. + * + * Whether error detection is enabled or disabled is specified in the + * \p check parameter. Valid values are #H5Z_ENABLE_EDC (default) and + * #H5Z_DISABLE_EDC. + * + * \note The initial error detection implementation, Fletcher32 checksum, + * supports error detection for chunked datasets only. + * + * \attention The Fletcher32 EDC checksum filter, set with H5Pset_fletcher32(), + * was added in HDF5 Release 1.6.0. In the original implementation, + * however, the checksum value was calculated incorrectly on + * little-endian systems. The error was fixed in HDF5 Release 1.6.3.\n + * As a result of this fix, an HDF5 library of Release 1.6.0 through + * Release 1.6.2 cannot read a dataset created or written with + * Release 1.6.3 or later if the dataset was created with the + * checksum filter and the filter is enabled in the reading + * library. (Libraries of Release 1.6.3 and later understand the + * earlier error and compensate appropriately.)\n + * \Bold{Work-around:} An HDF5 library of Release 1.6.2 or earlier + * will be able to read a dataset created or written with the + * checksum filter by an HDF5 library of Release 1.6.3 or later if + * the checksum filter is disabled for the read operation. This can + * be accomplished via an H5Pset_edc_check() call with the value + * #H5Z_DISABLE_EDC in the second parameter. This has the obvious + * drawback that the application will be unable to verify the + * checksum, but the data does remain accessible. + * + * \version 1.6.3 Error in checksum calculation on little-endian systems + * corrected in this release. + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check); + +/** + * \ingroup DXPL + * + * \brief Sets user-defined filter callback function + * + * \dxpl_id{plist_id} + * \param[in] func User-defined filter callback function + * \param[in] op_data User-defined input data for the callback function + * \return \herr_t + * + * \details H5Pset_filter_callback() sets the user-defined filter callback + * function \p func in the dataset transfer property list \p plist_id. + * + * The parameter \p op_data is a pointer to user-defined input data for + * the callback function and will be passed through to the callback + * function. + * + * The callback function \p func defines the actions an application is + * to take when a filter fails. The function prototype is as follows: + * \snippet H5Zpublic.h H5Z_filter_func_t_snip + * where \c filter indicates which filter has failed, \c buf and \c buf_size + * are used to pass in the failed data, and op_data is the required + * input data for this callback function. + * + * Valid callback function return values are #H5Z_CB_FAIL and #H5Z_CB_CONT. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void *op_data); + +/** + * \ingroup DXPL + * + * \brief Sets number of I/O vectors to be read/written in hyperslab I/O + * + * \dxpl_id{plist_id} + * \param[in] size Number of I/O vectors to accumulate in memory for I/O + * operations\n + * Must be greater than 1 (one)\n + * Default value: 1024 + * \return \herr_t + * + * \details H5Pset_hyper_vector_size() sets the number of I/O vectors to be + * accumulated in memory before being issued to the lower levels of + * the HDF5 library for reading or writing the actual data. + * + * The I/O vectors are hyperslab offset and length pairs and are + * generated during hyperslab I/O. + * + * The number of I/O vectors is passed in \p size to be set in the + * dataset transfer property list \p plist_id. \p size must be + * greater than 1 (one). + * + * H5Pset_hyper_vector_size() is an I/O optimization function; + * increasing vector_size should provide better performance, but the + * library will use more memory during hyperslab I/O. The default value + * of \p size is 1024. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); + +/** + * \ingroup DXPL + * + * \brief Sets the dataset transfer property list \p status + * + * \dxpl_id{plist_id} + * \param[in] status Status toggle of the dataset transfer property list + * \return \herr_t + * + * \deprecated This function is deprecated as it no longer has any effect; + * compound datatype field preservation is now core functionality in + * the HDF5 library. + * + * \details H5Pset_preserve() sets the dataset transfer property list status to + * \c 1 or \c 0. + * + * When reading or writing compound datatypes and the destination is + * partially initialized and the read/write is intended to initialize + * the other members, one must set this property to \c 1. Otherwise the + * I/O pipeline treats the destination datapoints as completely + * uninitialized. + * + * \todo Add missing version information: introduction, deprecation, etc. + * Why is the declaration not in the deprecated section? + * + */ +H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); + +/** + * \ingroup DXPL + * + * \brief Sets user-defined datatype conversion callback function + * + * \dxpl_id + * \param[in] op User-defined type conversion callback function + * \param[in] operate_data User-defined input data for the callback function + * \return \herr_t + * + * \details H5Pset_type_conv_cb() sets the user-defined datatype conversion + * callback function \p op in the dataset transfer property list \p + * dxpl_id + * + * The parameter operate_data is a pointer to user-defined input data + * for the callback function and will be passed through to the callback + * function. + * + * The callback function \p op defines the actions an application is to + * take when there is an exception during datatype conversion. The + * function prototype is as follows: + * \snippet H5Tpublic.h H5T_conv_except_func_t_snip + * + * \todo Add version information. + * + */ +H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); + +/** + * \ingroup DXPL + * + * \brief Sets the memory manager for variable-length datatype allocation in + * H5Dread() and H5Dvlen_reclaim() + * + * \dxpl_id{plist_id} + * \param[in] alloc_func User's allocate routine, or \c NULL for system \c malloc + * \param[in] alloc_info Extra parameter for user's allocation routine. + * Contents are ignored if preceding parameter is \c NULL. + * \param[in] free_func User's free routine, or \c NULL for system \c free + * \param[in] free_info Extra parameter for user's free routine. Contents are + * ignored if preceding parameter is \c NULL + * \return \herr_t + * + * \details H5Pset_vlen_mem_manager() sets the memory manager for + * variable-length datatype allocation in H5Dread() and free in + * H5Dvlen_reclaim(). + * + * The \p alloc_func and \p free_func parameters identify the memory + * management routines to be used. If the user has defined custom + * memory management routines, \p alloc_func and/or free_func should be + * set to make those routine calls (i.e., the name of the routine is + * used as the value of the parameter); if the user prefers to use the + * system's \c malloc and/or \c free, the \p alloc_func and \p + * free_func parameters, respectively, should be set to \c NULL + * + * The prototypes for these user-defined functions are as follows: + * \snippet H5MMpublic.h H5MM_allocate_t_snip + * + * \snippet H5MMpublic.h H5MM_free_t_snip + * + * The \p alloc_info and \p free_info parameters can be used to pass + * along any required information to the user's memory management + * routines. + * + * In summary, if the user has defined custom memory management + * routines, the name(s) of the routines are passed in the \p + * alloc_func and \p free_func parameters and the custom routines' + * parameters are passed in the \p alloc_info and \p free_info + * parameters. If the user wishes to use the system \c malloc and \c + * free functions, the \p alloc_func and/or \p free_func parameters are + * set to \c NULL and the \p alloc_info and \p free_info parameters are + * ignored. + * + * \todo Add version information. + */ +H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, + H5MM_free_t free_func, void *free_info); + #ifdef H5_HAVE_PARALLEL +/** + * \ingroup DXPL + * + * \brief Retrieves the type of chunk optimization that HDF5 actually performed + * on the last parallel I/O call (not necessarily the type requested) + * + * \dxpl_id{plist_id} + * \param[out] actual_chunk_opt_mode The type of chunk optimization performed by HDF5 + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list + * (DXPL) that has been suitably modified with H5Pset_dxpl_mpio(). + * However, HDF5 will sometimes ignore this request and perform independent + * I/O instead. This property allows the user to see what kind of I/O HDF5 + * actually performed. Used in conjunction with H5Pget_mpio_actual_io_mode(), + * this property allows the user to determine exactly what HDF5 did when + * attempting collective I/O. + * + * \details H5Pget_mpio_actual_chunk_opt_mode() retrieves the type of chunk + * optimization performed when collective I/O was requested. This + * property is set before I/O takes place, and will be set even if I/O + * fails. + * + * Valid values returned in \p actual_chunk_opt_mode: + * \snippet this H5D_mpio_actual_chunk_opt_mode_t_snip + * \click4more + * + * \since 1.8.8 + * + */ H5_DLL herr_t H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id, H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode); +/** + * \ingroup DXPL + * + * \brief Retrieves the type of I/O that HDF5 actually performed on the last + * parallel I/O call (not necessarily the type requested) + * + * \dxpl_id{plist_id} + * \param[out] actual_io_mode The type of I/O performed by this process + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list + * (DXPL) that has been suitably modified with H5Pset_dxpl_mpio(). + * However, HDF5 will sometimes ignore this request and perform independent + * I/O instead. This property allows the user to see what kind of I/O HDF5 + * actually performed. Used in conjunction with H5Pget_mpio_actual_chunk_opt_mode(), + * this property allows the user to determine exactly HDF5 did when + * attempting collective I/O. + * + * \details H5Pget_mpio_actual_io_mode() retrieves the type of I/O performed on + * the selection of the current process. This property is set after all + * I/O is completed; if I/O fails, it will not be set. + * + * Valid values returned in \p actual_io_mode: + * \snippet this H5D_mpio_actual_io_mode_t_snip + * \click4more + * + * \attention All processes do not need to have the same value. For example, if + * I/O is being performed using the multi chunk optimization scheme, + * one process's selection may include only chunks accessed + * collectively, while another may include chunks accessed + * independently. In this case, the first process will report + * #H5D_MPIO_CHUNK_COLLECTIVE while the second will report + * #H5D_MPIO_CHUNK_INDEPENDENT. + * + * \see H5Pget_mpio_no_collective_cause(), H5Pget_mpio_actual_chunk_opt_mode() + * + * \since 1.8.8 + * + */ H5_DLL herr_t H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode_t *actual_io_mode); +/** + * \ingroup DXPL + * + * \brief Retrieves local and global causes that broke collective I/O on the last + * parallel I/O call + * + * \dxpl_id{plist_id} + * \param[out] local_no_collective_cause An enumerated set value indicating the + * causes that prevented collective I/O in the local process + * \param[out] global_no_collective_cause An enumerated set value indicating + * the causes across all processes that prevented collective I/O + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list (DXPL) + * that has been suitably modified with H5P_SET_DXPL_MPIO. However, there are + * conditions that can cause HDF5 to forgo collective I/O and perform + * independent I/O. Such causes can be different across the processes of a + * parallel application. This function allows the user to determine what + * caused the HDF5 library to skip collective I/O locally, that is in the + * local process, and globally, across all processes. + * + * \details H5Pget_mpio_no_collective_cause() serves two purposes. It can be + * used to determine whether collective I/O was used for the last + * preceding parallel I/O call. If collective I/O was not used, the + * function retrieves the local and global causes that broke collective + * I/O on that parallel I/O call. The properties retrieved by this + * function are set before I/O takes place and are retained even when + * I/O fails. + * + * Valid values returned in \p local_no_collective_cause and \p + * global_no_collective_cause are as follows or, if there are multiple + * causes, a bitwise OR of the relevant causes; the numbers in the + * center column are the bitmask values: + * \snippet this H5D_mpio_no_collective_cause_t_snip + * \click4more + * + * \attention Each process determines whether it can perform collective I/O and + * broadcasts the result. Those results are combined to make a + * collective decision; collective I/O will be performed only if all + * processes can perform collective I/O.\n + * If collective I/O was not used, the causes that prevented it are + * reported by individual process by means of an enumerated set. The + * causes may differ among processes, so H5Pget_mpio_no_collective_cause() + * returns two property values. The first value is the one produced + * by the local process to report local causes. This local information + * is encoded in an enumeration, the \ref H5D_mpio_no_collective_cause_t + * described above, with all individual causes combined into a single + * enumeration value by means of a bitwise OR operation. The second + * value reports global causes; this global value is the result of a + * bitwise-OR operation across the values returned by all the processes. + * + * \since 1.8.10 + * + */ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no_collective_cause, uint32_t *global_no_collective_cause); #endif /* H5_HAVE_PARALLEL */ /* Link creation property list (LCPL) routines */ -H5_DLL herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd); +/** + * \ingroup ALCAPL + * + * \brief Determines whether property is set to enable creating missing + * intermediate groups + * + * \lcpl_id{plist_id} + * \param[out] crt_intmd Flag specifying whether to create intermediate + * groups upon creation of an object + * + * \return \herr_t + * + * \details H5Pget_create_intermediate_group() determines whether the link + * creation property list \p plist_id is set to allow functions + * that create objects in groups different from the current + * working group to create intermediate groups that may be + * missing in the path of a new or moved object. + * + * Functions that create objects in or move objects to a group + * other than the current working group make use of this + * property. H5Gcreate_anon() and H5Lmove() are examples of such + * functions. + * + * If \p crt_intmd is positive, missing intermediate groups will + * be created; if \p crt_intmd is non-positive, missing intermediate + * groups will not be created. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_create_intermediate_group(hid_t plist_id, unsigned *crt_intmd /*out*/); +/** + * \ingroup ALCAPL + * + * \brief Specifies in property list whether to create missing + * intermediate groups + * + * \lcpl_id{plist_id} + * \param[in] crt_intmd Flag specifying whether to create intermediate + * groups upon the creation of an object + * + * \return \herr_t + * + * \details H5Pset_create_intermediate_group() + * + * \since + * + */ +H5_DLL herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd); /* Group creation property list (GCPL) routines */ -H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); -H5_DLL herr_t H5Pget_local_heap_size_hint(hid_t plist_id, size_t *size_hint /*out*/); -H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); + +/** + * \ingroup GCPL + * + * \brief Returns the estimated link count and average link name length in a group + * + * \gcpl_id{plist_id} + * \param[out] est_num_entries The estimated number of links in the group + * referenced by \p plist_id + * \param[out] est_name_len The estimated average length of line names in the group + * referenced by \p plist_id + * \return \herr_t + * + * \details H5Pget_est_link_info() retrieves two settings from the group creation + * property list \p plist_id: the estimated number of links that are + * expected to be inserted into a group created with the property list + * and the estimated average length of those link names. + * + * The estimated number of links is returned in \p est_num_entries. The + * limit for \p est_num_entries is 64 K. + * + * The estimated average length of the anticipated link names is returned + * in \p est_name_len. The limit for \p est_name_len is 64 K. + * + * See \ref_group_impls for a discussion of the available types of HDF5 + * group structures. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_est_link_info(hid_t plist_id, unsigned *est_num_entries /* out */, + unsigned *est_name_len /* out */); +/** + * \ingroup GCPL + * + * \brief Queries whether link creation order is tracked and/or indexed in + * a group + * + * \param[in] plist_id Group or file creation property list + * identifier + * \param[out] crt_order_flags Creation order flag(s) + * + * \return \herr_t + * + * \details H5Pget_link_creation_order() queries the group or file creation + * property list, \p plist_id, and returns a flag indicating whether + * link creation order is tracked and/or indexed in a group. + * + * See H5Pset_link_creation_order() for a list of valid creation + * order flags, as passed in \p crt_order_flags, and their + * meanings. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_flags /* out */); +/** + * \ingroup GCPL + * + * \brief Queries the settings for conversion between compact and dense + * groups + * + * \gcpl_id{plist_id} + * \param[out] max_compact Maximum number of links for compact storage + * \param[out] min_dense Minimum number of links for dense storage + * + * \return \herr_t + * + * \details H5Pget_link_phase_change() queries the maximum number of + * entries for a compact group and the minimum number of links + * to require before converting a group to a dense form. + * + * In the compact format, links are stored as messages in the + * group’s header. In the dense format, links are stored in a + * fractal heap and indexed with a version 2 B-tree. + * + * \p max_compact is the maximum number of links to store as + * header messages in the group header before converting the + * group to the dense format. Groups that are in the compact + * format and exceed this number of links are automatically + * converted to the dense format. + * + * \p min_dense is the minimum number of links to store in the + * dense format. Groups which are in dense format and in which + * the number of links falls below this number are automatically + * converted back to the compact format. + * + * In the compact format, links are stored as messages in the + * group’s header. In the dense format, links are stored in a + * fractal heap and indexed with a version 2 B-tree. + * + * See H5Pset_link_phase_change() for a discussion of + * traditional, compact, and dense group storage. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_link_phase_change(hid_t plist_id, unsigned *max_compact /*out*/, unsigned *min_dense /*out*/); +/** + * \ingroup GCPL + * + * \brief Retrieves the anticipated size of the local heap for original-style + * groups + * + * \gcpl_id{plist_id} + * \param[out] size_hint Anticipated size of local heap + * \return \herr_t + * + * \details H5Pget_local_heap_size_hint() queries the group creation property + * list, \p plist_id, for the anticipated size of the local heap, \p + * size_hint, for original-style groups, i.e., for groups of the style + * used prior to HDF5 Release 1.8.0. See H5Pset_local_heap_size_hint() + * for further discussion. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_local_heap_size_hint(hid_t plist_id, size_t *size_hint /*out*/); +/** + * \ingroup GCPL + * + * \brief Sets estimated number of links and length of link names in a group + * + * \gcpl_id{plist_id} + * \param[in] est_num_entries Estimated number of links to be inserted into group + * \param[in] est_name_len Estimated average length of link names + * \return \herr_t + * + * \details H5Pset_est_link_info() inserts two settings into the group creation + * property list plist_id: the estimated number of links that are + * expected to be inserted into a group created with the property list + * and the estimated average length of those link names. + * + * The estimated number of links is passed in \p est_num_entries. The + * limit for \p est_num_entries is 64 K. + * + * The estimated average length of the anticipated link names is passed + * in \p est_name_len. The limit for \p est_name_len is 64 K. + * + * The values for these two settings are multiplied to compute the + * initial local heap size (for old-style groups, if the local heap + * size hint is not set) or the initial object header size for + * (new-style compact groups; see \ref_group_impls). Accurately setting + * these parameters will help reduce wasted file space. + * + * If a group is expected to have many links and to be stored in dense + * format, set \p est_num_entries to 0 (zero) for maximum + * efficiency. This will prevent the group from being created in the + * compact format. + * + * See \ref_group_impls for a discussion of the available types of HDF5 + * group structures. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_est_link_info(hid_t plist_id, unsigned est_num_entries, unsigned est_name_len); -H5_DLL herr_t H5Pget_est_link_info(hid_t plist_id, unsigned *est_num_entries /* out */, - unsigned *est_name_len /* out */); +/** + * \ingroup GCPL + * + * \brief Sets creation order tracking and indexing for links in a group + * + * \param[in] plist_id Group or file creation property list + * identifier + * \param[out] crt_order_flags Creation order flag(s) + * + * \return \herr_t + * + * \details H5Pset_link_creation_order() sets flags for tracking and + * indexing links on creation order in groups created with the + * group (or file) creation property list \p plist_id. + * + * \p crt_order_flags contains flags with the following meanings: + * + * <table> + * <tr> + * <td>#H5P_CRT_ORDER_TRACKED</td> + * <td>Link creation order is tracked but not necessarily + * indexed</td> + * </tr> + * <tr> + * <td>#H5P_CRT_ORDER_INDEXED</td> + * <td>Link creation order is indexed (requires + * #H5P_CRT_ORDER_TRACKED)</td> + * </tr> + * </table> + * + * The default behavior is that links are tracked and indexed by + * name, and link creation order is neither tracked nor indexed. + * The name is always the primary index for links in a group. + * + * H5Pset_link_creation_order() can be used to set link creation + * order tracking, or to set link creation order tracking and + * indexing. + * + * If (#H5P_CRT_ORDER_TRACKED | #H5P_CRT_ORDER_INDEXED) is + * specified for \p crt_order_flags, then links will be tracked + * and indexed by creation order. The creation order is added as + * a secondary index and enables faster queries and iterations + * by creation order. + * + * If just #H5P_CRT_ORDER_TRACKED is specified for + * \p crt_order_flags, then links will be tracked by creation + * order, but not indexed by creation order. Queries and iterations + * by creation order will work but will be much slower for large + * groups than if #H5P_CRT_ORDER_INDEXED had been included. + * + * \note If a creation order index is to be built, it must be specified in + * the group creation property list. HDF5 currently provides no + * mechanism to turn on link creation order tracking at group + * creation time and to build the index later. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_link_creation_order(hid_t plist_id, unsigned crt_order_flags); -H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_flags /* out */); +/** + * \ingroup GCPL + * + * \brief Sets the parameters for conversion between compact and dense + * groups + * + * \gcpl_id{plist_id} + * \param[in] max_compact Maximum number of links for compact storage + * (\a Default: 8) + * \param[in] min_dense Minimum number of links for dense storage + * (\a Default: 6) + * + * \return \herr_t + * + * \details H5Pset_link_phase_change() sets the maximum number of entries + * for a compact group and the minimum number of links to allow + * before converting a dense group back to the compact format. + * + * \p max_compact is the maximum number of links to store as + * header messages in the group header before converting the + * group to the dense format. Groups that are in compact format + * and which exceed this number of links are automatically + * converted to dense format. + * + * \p min_dense is the minimum number of links to store in the + * dense format. Groups which are in dense format and in which + * the number of links falls below this threshold are + * automatically converted to compact format. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); +/** + * \ingroup GCPL + * + * \brief Specifies the anticipated maximum size of a local heap + * + * \gcpl_id{plist_id} + * \param[in] size_hint Anticipated maximum size in bytes of local heap + * \return \herr_t + * + * \details H5Pset_local_heap_size_hint() is used with original-style HDF5 + * groups (see “Motivation” below) to specify the anticipated maximum + * local heap size, size_hint, for groups created with the group + * creation property list \p plist_id. The HDF5 library then uses \p + * size_hint to allocate contiguous local heap space in the file for + * each group created with \p plist_id. + * + * For groups with many members or very few members, an appropriate + * initial value of \p size_hint would be the anticipated number of + * group members times the average length of group member names, plus a + * small margin: + * \code + * size_hint = max_number_of_group_members * + * (average_length_of_group_member_link_names + 2) + * \endcode + * If it is known that there will be groups with zero members, the use + * of a group creation property list with \p size_hint set to to 1 (one) + * will guarantee the smallest possible local heap for each of those groups. + * + * Setting \p size_hint to zero (0) causes the library to make a + * reasonable estimate for the default local heap size. + * + * \par Motivation: + * In situations where backward-compatibility is required, specifically, when + * libraries prior to HDF5 Release 1.8.0 may be used to read the file, groups + * must be created and maintained in the original style. This is HDF5’s default + * behavior. If backward compatibility with pre-1.8.0 libraries is not a concern, + * greater efficiencies can be obtained with the new-format compact and indexed + * groups. See <a href="https://portal.hdfgroup.org/display/HDF5/Groups">Group + * implementations in HDF5</a> in the \ref H5G API introduction (at the bottom).\n + * H5Pset_local_heap_size_hint() is useful for tuning file size when files + * contain original-style groups with either zero members or very large + * numbers of members.\n + * The original style of HDF5 groups, the only style available prior to HDF5 + * Release 1.8.0, was well-suited for moderate-sized groups but was not optimized + * for either very small or very large groups. This original style remains the + * default, but two new group implementations were introduced in HDF5 Release 1.8.0: + * compact groups to accommodate zero to small numbers of members and indexed groups + * for thousands or tens of thousands of members ... or millions, if that's what + * your application requires.\n + * The local heap size hint, \p size_hint, is a performance tuning parameter for + * original-style groups. As indicated above, an HDF5 group may have zero, a handful, + * or tens of thousands of members. Since the original style of HDF5 groups stores the + * metadata for all of these group members in a uniform format in a local heap, the size + * of that metadata (and hence, the size of the local heap) can vary wildly from group + * to group. To intelligently allocate space and to avoid unnecessary fragmentation of + * the local heap, it can be valuable to provide the library with a hint as to the local + * heap’s likely eventual size. This can be particularly valuable when it is known that + * a group will eventually have a great many members. It can also be useful in conserving + * space in a file when it is known that certain groups will never have any members. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); /* String creation property list (STRCPL) routines */ -H5_DLL herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding); +/** + * \ingroup ALCAPL + * + * \brief Retrieves the character encoding used to create a link or + * attribute name + * + * \param[in] plist_id Link creation or attribute creation property list + * identifier + * \param[out] encoding String encoding character set + * + * \return \herr_t + * + * \details H5Pget_char_encoding() retrieves the character encoding used + * to encode link or attribute names that are created with the + * property list \p plist_id. + * + * Valid values for \p encoding are defined in H5Tpublic.h and + * include the following: + * + * \csets + * + * \note H5Pget_char_encoding() retrieves the character set used for an + * HDF5 link or attribute name while H5Tget_cset() retrieves the + * character set used in a character or string datatype. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/); +/** + * \ingroup ALCAPL + * + * \brief Sets the character encoding used to encode link and attribute + * names + * + * \param[in] plist_id Link creation or attribute creation property list + * identifier + * \param[in] encoding String encoding character set + * + * \return \herr_t + * + * \details H5Pset_char_encoding() sets the character encoding used for + * the names of links (which provide the names by which objects + * are referenced) or attributes created with the property list + * \p plist_id. + * + * Valid values for encoding include the following: + * \csets + * \details For example, if the character set for the property list + * \p plist_id is set to #H5T_CSET_UTF8, link names pointing to + * objects created with the link creation property list + * \p plist_id will be encoded using the UTF-8 character set. + * Similarly, names of attributes created with the attribute + * creation property list \p plist_id will be encoded as UTF-8. + * + * ASCII and UTF-8 Unicode are the only currently supported + * character encodings. Extended ASCII encodings (for example, + * ISO 8859) are not supported. This encoding policy is not + * enforced by the HDF5 library. Using encodings other than + * ASCII and UTF-8 can lead to compatibility and usability + * problems. + * + * \note H5Pset_char_encoding() sets the character set used for an + * HDF5 link or attribute name while H5Tset_cset() sets the + * character set used in a character or string datatype. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding); /* Link access property list (LAPL) routines */ -H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); -H5_DLL herr_t H5Pget_nlinks(hid_t plist_id, size_t *nlinks); -H5_DLL herr_t H5Pset_elink_prefix(hid_t plist_id, const char *prefix); +/** + * \ingroup LAPL + * + * \brief Retrieves the external link traversal file access flag from the + * specified link access property list + * + * \lapl_id + * \param[out] flags File access flag for link traversal + * + * \return \herr_t + * + * \details H5Pget_elink_acc_flags() retrieves the file access flag used + * to open an external link target file from the specified link + * access property list. + * + * Valid values for \p flags include: + * \li #H5F_ACC_RDWR - Files opened through external links will + * be opened with write access + * \li #H5F_ACC_RDONLY - Files opened through external links will + * be opened with read-only access + * \li #H5F_ACC_DEFAULT - Files opened through external links will + * be opened with the same access flag as + * the parent file + * + * The value returned, if it is not #H5F_ACC_DEFAULT, will + * override the default access flag, which is the access flag + * used to open the parent file. + * + * <b>Example Usage:</b> + * The following code retrieves the external link access flag + * settings on the link access property list \p lapl_id into a + * local variable: + * <pre> + * unsigned acc_flags; + * status = H5Pget_elink_acc_flags(lapl_id, &acc_flags); + * </pre> + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pget_elink_acc_flags(hid_t lapl_id, unsigned *flags); +/** + * \ingroup LAPL + * + * \brief Retrieves the external link traversal callback function from the + * specified link access property list + * + * \lapl_id + * \param[out] func User-defined external link traversal callback + * function + * \param[out] op_data User-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pget_elink_cb() retrieves the user-defined external link + * traversal callback function defined in the specified link + * access property list. + * + * The callback function may adjust the file access property + * list and file access flag to use when opening a file through + * an external link. The callback will be executed by the HDF5 + * library immediately before opening the target file. + * + * <b>Failure Modes:</b> H5Pget_elink_cb() will fail if the link + * access property list identifier, \p lapl_id, is invalid. + * + * An invalid function pointer or data pointer, \p func or + * \p op_data respectively, may cause a segmentation fault or an + * invalid memory access. + * + * <b>Example Usage:</b> The following code retrieves the external + * link callback settings on the link access property list + * \p lapl_id into local variables: + * <pre> + * H5L_elink_traverse_t elink_callback_func; + * void *elink_callback_udata; + * status = H5Pget_elink_cb (lapl_id, &elink_callback_func, + * &elink_callback_udata); + * </pre> + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pget_elink_cb(hid_t lapl_id, H5L_elink_traverse_t *func, void **op_data); +/** + * \ingroup LAPL + * + * \brief Retrieves the file access property list identifier associated + * with the link access property list + * + * \lapl_id + * + * \return \hid_t{file access property list} + * + * \details H5Pget_elink_fapl() retrieves the file access property list + * identifier that is set for the link access property list + * identifier, \p lapl_id. The library uses this file access + * property list identifier to open the target file for the + * external link access. When no such identifier is set, this + * routine returns #H5P_DEFAULT. + * + * \see H5Pset_elink_fapl() and H5Lcreate_external(). + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Pget_elink_fapl(hid_t lapl_id); +/** + * \ingroup LAPL + * + * \brief Retrieves prefix applied to external link paths + * + * \lapl_id{plist_id} + * \param[out] prefix Prefix applied to external link paths + * \param[in] size Size of prefix, including null terminator + * + * \return If successful, returns a non-negative value specifying the size + * in bytes of the prefix without the NULL terminator; otherwise + * returns a negative value. + * + * \details H5Pget_elink_prefix() retrieves the prefix applied to the + * path of any external links traversed. + * + * When an external link is traversed, the prefix is retrieved + * from the link access property list \p plist_id, returned in + * the user-allocated buffer pointed to by \p prefix, and + * prepended to the filename stored in the external link. + * + * The size in bytes of the prefix, including the NULL terminator, + * is specified in \p size. If size is unknown, a preliminary + * H5Pget_elink_prefix() call with the pointer \p prefix set to + * NULL will return the size of the prefix without the NULL + * terminator. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Pget_elink_prefix(hid_t plist_id, char *prefix, size_t size); -H5_DLL hid_t H5Pget_elink_fapl(hid_t lapl_id); -H5_DLL herr_t H5Pset_elink_fapl(hid_t lapl_id, hid_t fapl_id); -H5_DLL herr_t H5Pset_elink_acc_flags(hid_t lapl_id, unsigned flags); -H5_DLL herr_t H5Pget_elink_acc_flags(hid_t lapl_id, unsigned *flags); -H5_DLL herr_t H5Pset_elink_cb(hid_t lapl_id, H5L_elink_traverse_t func, void *op_data); -H5_DLL herr_t H5Pget_elink_cb(hid_t lapl_id, H5L_elink_traverse_t *func, void **op_data); +/** + * \ingroup LAPL + * + * \brief Retrieves the maximum number of link traversals + * + * \lapl_id{plist_id} + * \param[out] nlinks Maximum number of links to traverse + * + * \return \herr_t + * + * \details H5Pget_nlinks() retrieves the maximum number of soft or + * user-defined link traversals allowed, \p nlinks, before the + * library assumes it has found a cycle and aborts the traversal. + * This value is retrieved from the link access property list + * \p plist_id. + * + * The limit on the number of soft or user-defined link traversals + * is designed to terminate link traversal if one or more links + * form a cycle. User control is provided because some files may + * have legitimate paths formed of large numbers of soft or + * user-defined links. This property can be used to allow + * traversal of as many links as desired. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_nlinks(hid_t plist_id, size_t *nlinks); +/** + * \ingroup LAPL + * + * \brief Sets the external link traversal file access flag in a link + * access property list + * + * \lapl_id + * \param[in] flags The access flag for external link traversal + * + * \return \herr_t + * + * \details H5Pset_elink_acc_flags() specifies the file access flag to use + * to open the target file of an external link. This allows + * read-only access of files reached through an external link in + * a file opened with write access, or vice-versa. + * + * Valid values for \p flags include: + * \li #H5F_ACC_RDWR - Causes files opened through external links + * to be opened with write access + * \li #H5F_ACC_RDONLY - Causes files opened through external + * links to be opened with read-only access + * \li #H5F_ACC_DEFAULT - Removes any external link file access + * flag setting from \p lapl_id, causing the file access flag + * setting to be taken from the parent file + * + * The library will normally use the file access flag used to + * open the parent file as the file access flag for the target + * file. This function provides a way to override that behavior. + * The external link traversal callback function set by + * H5Pset_elink_cb() can override the setting from + * H5Pset_elink_acc_flags(). + * + * <b>Motivation:</b> H5Pset_elink_acc_flags() is used to adjust the + * file access flag used to open files reached through external links. + * This may be useful to, for example, prevent modifying files + * accessed through an external link. Otherwise, the target file is + * opened with whatever flag was used to open the parent. + * + * <b>Example Usage:</b> The following code sets the link access + * property list \p lapl_id to open external link target files with + * read-only access: + * <pre> + * status = H5Pset_elink_acc_flags(lapl_id, H5F_ACC_RDONLY); + * </pre> + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pset_elink_acc_flags(hid_t lapl_id, unsigned flags); +/** + * \ingroup LAPL + * + * \brief Sets the external link traversal callback function in a link + * access property list + * + * \lapl_id + * \param[in] func User-defined external link traversal callback + * function + * \param[in] op_data User-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pset_elink_cb() sets a user-defined external link traversal + * callback function in the link access property list \p lapl_id. + * The callback function \p func must conform to the prototype + * specified in #H5L_elink_traverse_t. + * + * The callback function may adjust the file access property + * list and file access flags to use when opening a file through + * an external link. The callback will be executed by the HDF5 + * library immediately before opening the target file. + * + * The callback will be made after the file access property list + * set by H5Pset_elink_fapl() and the file access flag set by + * H5Pset_elink_acc_flags() are applied, so changes made by this + * callback function will take precedence. + * + * \attention A file close degree property setting (H5Pset_fclose_degree()) + * in this callback function or an associated property list will + * be ignored. A file opened by means of traversing an external + * link is always opened with the weak file close degree + * property setting, #H5F_CLOSE_WEAK. + * + * <b>Motivation:</b> H5Pset_elink_cb() is used to specify a + * callback function that is executed by the HDF5 library when + * traversing an external link. This provides a mechanism to set + * specific access permissions, modify the file access property + * list, modify the parent or target file, or take any other + * user-defined action. This callback function is used in + * situations where the HDF5 library's default behavior is not + * suitable. + * + * <b>Failure Modes:</b> H5Pset_elink_cb() will fail if the link + * access property list identifier, \p lapl_id, is invalid or if + * the function pointer, \p func, is NULL. + * + * An invalid function pointer, \p func, will cause a segmentation + * fault or other failure when an attempt is subsequently made to + * traverse an external link. + * + * <b>Example Usage:</b> + * This example defines a callback function that prints the name + * of the target file every time an external link is followed, and + * sets this callback function on \p lapl_id. + * <pre> + * herr_t elink_callback(const char *parent_file_name, const char + * *parent_group_name, const char *child_file_name, const char + * *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data) { + * puts(child_file_name); + * return 0; + * } + * int main(void) { + * hid_t lapl_id = H5Pcreate(H5P_LINK_ACCESS); + * H5Pset_elink_cb(lapl_id, elink_callback, NULL); + * ... + * } + * </pre> + * + * + * \since 1.8.3 + * + */ +H5_DLL herr_t H5Pset_elink_cb(hid_t lapl_id, H5L_elink_traverse_t func, void *op_data); +/** + * \ingroup LAPL + * + * \brief Sets a file access property list for use in accessing a file + * pointed to by an external link + * + * \lapl_id + * \fapl_id + * + * \return \herr_t + * + * \details H5Pset_elink_fapl() sets the file access property list, + * \p fapl_id, to be used when accessing the target file of an + * external link associated with \p lapl_id. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_elink_fapl(hid_t lapl_id, hid_t fapl_id); +/** + * \ingroup LAPL + * + * \brief Sets prefix to be applied to external link paths + * + * \lapl_id{plist_id} + * \param[in] prefix Prefix to be applied to external link paths + * + * \return \herr_t + * + * \details H5Pset_elink_prefix() sets the prefix to be applied to the + * path of any external links traversed. The prefix is prepended + * to the filename stored in the external link. + * + * The prefix is specified in the user-allocated buffer \p prefix + * and set in the link access property list \p plist_id. The buffer + * should not be freed until the property list has been closed. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_elink_prefix(hid_t plist_id, const char *prefix); +/** + * \ingroup LAPL + * + * \brief Sets maximum number of soft or user-defined link traversals + * + * \lapl_id{plist_id} + * \param[in] nlinks Maximum number of links to traverse + * + * \return \herr_t + * + * \details H5Pset_nlinks() sets the maximum number of soft or user-defined + * link traversals allowed, \p nlinks, before the library assumes + * it has found a cycle and aborts the traversal. This value is + * set in the link access property list \p plist_id. + * + * The limit on the number of soft or user-defined link traversals + * is designed to terminate link traversal if one or more links + * form a cycle. User control is provided because some files may + * have legitimate paths formed of large numbers of soft or + * user-defined links. This property can be used to allow + * traversal of as many links as desired. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); /* Object copy property list (OCPYPL) routines */ -H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned crt_intmd); -H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *crt_intmd /*out*/); +/** + * \ingroup OCPPL + * + * \brief Adds a path to the list of paths that will be searched in the + * destination file for a matching committed datatype + * + * \param[in] plist_id Object copy property list identifier + * \param[in] path The path to be added + * + * \return \herr_t + * + * \details H5Padd_merge_committed_dtype_path() adds a path, \p path, + * which points to a committed datatype, to the current list of + * suggested paths stored in the object copy property list + * \p plist_id. The search as described in the next paragraph is + * effective only if the #H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is + * enabled in the object copy property list via + * H5Pset_copy_object(). + * + * When copying a committed datatype, a dataset with a committed + * datatype, or an object with an attribute of a committed + * datatype, the default behavior of H5Ocopy() is to search for + * a matching committed datatype: + * <ol> + * <li> First search the list of suggested paths in the object + * copy property list.</li> + * <li> Then, if no match has been found, search all the committed + * datatypes in the destination file. + * </ol> + * The default Step 2 in this search process can be changed by + * setting a callback function (see H5Pset_mcdt_search_cb()). + * + * Two datatypes are determined equal if their descriptions are + * identical, in a manner similar to H5Tequal(). If either + * committed datatype has one or more attributes, then all + * attributes must be present in both committed datatypes and they + * must be identical. Two attributes are considered identical if + * their datatype description, dataspace, and raw data values are + * the same. However, if an attribute uses a committed datatype, + * that committed datatype’s attributes will not be compared. + * + * If a match is found, H5Ocopy() will perform the following in + * the destination file: + * \li For a committed datatype, the library will create a hard + * link to the found datatype. + * \li For a dataset that uses a committed datatype, the library + * will modify the copied dataset to use the found committed + * datatype as its datatype. + * \li For an object with an attribute of a committed datatype, + * the library will modify the copied object’s attribute to + * use the found committed datatype as its datatype. + * + * If no match is found, H5Ocopy() will perform the following in + * the destination file: + * \li For a committed datatype, the library will copy it as it + * would any other object, creating a named committed + * datatype at the destination. That is, the library will + * create a committed datatype that is accessible in the + * file by a unique path. + * \li For a dataset that uses a committed datatype, the + * library will copy the datatype as an anonymous + * committed datatype and use that as the dataset’s + * datatype. + * \li For an object with an attribute of a committed datatype, + * the library will copy the datatype as an anonymous + * committed datatype and use that as the attribute’s + * datatype. + * + * \b Motivation: H5Padd_merge_committed_dtype_path() provides a + * means to override the default behavior of H5Ocopy() when + * #H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is set in an object + * copy property list. + * H5Padd_merge_committed_dtype_path() is the mechanism for + * suggesting search paths where H5Ocopy() will look for a + * matching committed datatype. This can be substantially + * faster than the default approach of searching the entire + * destination file for a match. + * + * \b Example \b Usage: This example adds two paths to the object + * copy property list. H5Ocopy() will search the two suggested + * paths for a match before searching all the committed datatypes + * in the destination file. + * + * <pre> + * int main(void) { + * hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY); + * + * H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG); + * H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA"); + * H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dset"); + * H5Ocopy(...ocpypl_id...); + * ... + * ... + * } + * </pre> + * + * \note H5Padd_merge_committed_dtype_path() will fail if the object + * copy property list is invalid. + * It will also fail if there is insufficient memory when + * duplicating \p path. + * + * \see + * \li H5Ocopy() + * \li #H5O_mcdt_search_cb_t + * \li H5Padd_merge_committed_dtype_path() + * \li H5Pfree_merge_committed_dtype_paths() + * \li H5Pget_mcdt_search_cb() + * \li H5Pset_copy_object() + * \li H5Pset_mcdt_search_cb() + * \li \ref_h5ocopy + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path); +/** + * \ingroup OCPPL + * + * \brief Clears the list of paths stored in the object copy property list + * + * \param[in] plist_id Object copy property list identifier + * + * \return \herr_t + * + * \details H5Pfree_merge_committed_dtype_paths() clears the suggested + * paths stored in the object copy property list \p plist_id. + * These are the suggested paths previously set with + * H5Padd_merge_committed_dtype_path(). + * + * \b Example \b Usage: This example adds a suggested path to the + * object copy property list, does the copy, clears the list, and + * then adds a new suggested path to the list for another copy. + * + * <pre> + * int main(void) { + * hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY); + * + * H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG); + * H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA"); + * H5Ocopy(...ocpypl_id...); + * ... + * ... + * H5Pfree_merge_committed_dtype_paths(ocpypl_id); + * H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dtypeB"); + * H5Ocopy(...ocpypl_id...); + * ... + * ... + * } + * </pre> + * + * \note H5Pfree_merge_committed_dtype_paths() will fail if the + * object copy property list is invalid. + * + * \see + * \li H5Ocopy() + * \li #H5O_mcdt_search_cb_t + * \li H5Padd_merge_committed_dtype_path() + * \li H5Pfree_merge_committed_dtype_paths() + * \li H5Pget_mcdt_search_cb() + * \li H5Pset_copy_object() + * \li H5Pset_mcdt_search_cb() + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); -H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data); +/** + * \ingroup OCPPL + * + * \brief Retrieves the properties to be used when an object is copied + * + * \param[in] plist_id Object copy property list identifier + * \param[out] copy_options Copy option(s) set in the object copy property + * list + * + * \return \herr_t + * + * \details H5Pget_copy_object() retrieves the properties currently + * specified in the object copy property list \p plist_id, which + * will be invoked when a new copy is made of an existing object. + * + * \p copy_options is a bit map indicating the flags, or + * properties, governing object copying that are set in the + * property list \p plist_id. + * + * The available flags are described in H5Pset_copy_object(). + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/); +/** + * \ingroup OCPPL + * + * \brief Retrieves the callback function from the specified object copy + * property list + * + * \param[in] plist_id Object copy property list identifier + * \param[out] func User-defined callback function + * \param[out] op_data User-defined data for the callback + * function + * + * \return \herr_t + * + * \details H5Pget_mcdt_search_cb() retrieves the user-defined callback + * function and the user data that are set via + * H5Pset_mcdt_search_cb() in the object copy property list + * \p plist_id. + * + * The callback function will be returned in the parameter \p func + * and the user data will be returned in the parameter \p op_data. + * + * \note H5Pget_mcdt_search_cb() will fail if the object copy property + * list is invalid. + * + * \see + * \li H5Ocopy() + * \li #H5O_mcdt_search_cb_t + * \li H5Padd_merge_committed_dtype_path() + * \li H5Pfree_merge_committed_dtype_paths() + * \li H5Pget_mcdt_search_cb() + * \li H5Pset_copy_object() + * \li H5Pset_mcdt_search_cb() + * \li \ref_h5ocopy + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data); +/** + * \ingroup OCPPL + * + * \brief Sets properties to be used when an object is copied + * + * \param[in] plist_id Object copy property list identifier + * \param[out] copy_options Copy option(s) to be set + * + * \return \herr_t + * + * \details H5Pset_copy_object() sets properties in the object copy + * property list \p plist_id. When an existing object is copied, + * that property list will determine how the new copy is created. + * + * The following flags are available for use in an object copy + * property list: + * + * <table> + * <tr> + * <td>#H5O_COPY_SHALLOW_HIERARCHY_FLAG</td> + * <td>Copy only immediate members of a group<br /> + * <em>Default behavior, without flag:</em> Recursively + * copy all objects in and below the group.</td> + * </tr> + * <tr> + * <td>#H5O_COPY_EXPAND_SOFT_LINK_FLAG</td> + * <td>Expand soft links into new objects<br /> + * <em>Default behavior, without flag:</em> Copy soft + * links as they are.</td> + * </tr> + * <tr> + * <td>#H5O_COPY_EXPAND_EXT_LINK_FLAG</td> + * <td>Expand external link into new objects<br /> + * <em>Default behavior, without flag:</em> Copy external + * links as they are.</td> + * </tr> + * <tr> + * <td>#H5O_COPY_EXPAND_REFERENCE_FLAG</td> + * <td>Copy objects that are pointed to by references and + * update reference values in destination file<br /> + * <em>Default behavior, without flag:</em> Set reference + * values in destination file to zero (0)</td> + * </tr> + * <tr> + * <td>#H5O_COPY_WITHOUT_ATTR_FLAG</td> + * <td>Copy object without copying attributes<br /> + * <em>Default behavior, without flag:</em> Copy object + * with all its attributes</td> + * </tr> + * <tr> + * <td>#H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG</td> + * <td>Use a matching committed datatype in the destination + * file when copying a committed datatype, a dataset with + * a committed datatype, or an object with an attribute + * of committed datatype <br /> + * <em>Default behavior without flag:</em> + * + * \li A committed datatype in the source will be copied to + * the destination as a committed datatype. + * \li If a dataset in the source uses a committed + * datatype or an object in the source has an attribute + * of a committed datatype, that committed datatype will + * be written to the destination as an anonymous + * committed datatype. + * If copied in a single H5Ocopy() operation, objects + * that share a committed datatype in the source will + * share an anonymous committed dataype in the + * destination copy. Subsequent H5Ocopy() operations, + * however, will be unaware of prior anonymous committed + * dataypes and will create new ones. + * + * See the “See Also” section immediately below for + * functions related to the use of this flag.</td> + * </tr> + * </table> + * + * \see + * Functions and a callback function used to tune committed datatype + * copying behavior: + * \li #H5O_mcdt_search_cb_t + * \li H5Padd_merge_committed_dtype_path() + * \li H5Pfree_merge_committed_dtype_paths() + * \li H5Pget_mcdt_search_cb() + * \li H5Pset_copy_object() + * \li H5Pset_mcdt_search_cb() + * \li \ref_h5ocopy + * + * \version 1.8.9 #H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG added in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned copy_options); +/** + * \ingroup OCPPL + * + * \brief Sets the callback function that H5Ocopy() will invoke before + * searching the entire destination file for a matching committed + * datatype + * + * \param[in] plist_id Object copy property list identifier + * \param[in] func User-defined callback function + * \param[in] op_data User-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pset_mcdt_search_cb() allows an application to set a + * callback function, \p func, that will be invoked before + * searching the destination file for a matching committed + * datatype. The default, global search process is described in + * H5Padd_merge_committed_dtype_path(). + * + * The callback function must conform to the #H5O_mcdt_search_cb_t + * prototype and will return an instruction for one of the + * following actions: + * + * \li Continue the search for a matching committed datatype in + * the destination file. + * \li Discontinue the search for a matching committed datatype. + * H5Ocopy() will then apply the default behavior of creating + * an anonymous committed datatype. + * \li Abort the copy operation and exit H5Ocopy(). + * + * \b Motivation: H5Pset_mcdt_search_cb() provides the means to + * define a callback function. An application can then use that + * callback to take an additional action before the default search + * of all committed datatypes in the destination file or to take an + * action that replaces the default search. This mechanism is + * intended to improve performance when the global search might + * take a long time. + * + * \b Example \b Usage: This example defines a callback function in + * the object copy property list. + * + * <pre> + * static H5O_mcdt_search_ret_t + * mcdt_search_cb(void *_udata) + * { + * H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata); + * + * return(action); + * } + * + * int main(void) { + * hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY); + * + * H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG); + * H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA"); + * + * action = H5O_MCDT_SEARCH_STOP; + * H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action); + * H5Ocopy(...ocpypl_id...); + * ... + * ... + * } + * </pre> + * + * \note H5Pset_mcdt_search_cb() will fail if the + * object copy property list is invalid. + * + * \warning If the callback function return value causes H5Ocopy() to + * abort, the destination file may be left in an inconsistent or + * corrupted state. + * + * \see + * \li H5Ocopy() + * \li #H5O_mcdt_search_cb_t + * \li H5Padd_merge_committed_dtype_path() + * \li H5Pfree_merge_committed_dtype_paths() + * \li H5Pget_mcdt_search_cb() + * \li H5Pset_copy_object() + * \li H5Pset_mcdt_search_cb() + * \li \ref_h5ocopy + * + * \since 1.8.9 + * + */ +H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data); /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -429,22 +7508,363 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, #define H5P_NO_CLASS H5P_ROOT /* Typedefs */ +/** + * \ingroup GPLOA + * + * \brief Registers a permanent property with a property list class + * + * \plistcls_id{cls_id} + * \param[in] name Name of property to register + * \param[in] size Size of property in bytes + * \param[in] def_value Default value for property in newly created + * property lists + * \param[in] prp_create Callback routine called when a property list is + * being created and the property value will be + * initialized + * \param[in] prp_set Callback routine called before a new value is + * copied into the property's value + * \param[in] prp_get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_del Callback routine called when a property is deleted + * from a property list + * \param[in] prp_copy Callback routine called when a property is copied + * from a property list + * \param[in] prp_close Callback routine called when a property list is + * being closed and the property value will be + * disposed of + * + * \return \herr_t + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pregister2() or the macro H5Pregister(). + * + * \details H5Pregister1() registers a new property with a property list + * class. The property will exist in all property list objects + * of that class after this routine is finished. The name of + * the property must not already exist. The default property + * value must be provided and all new property lists created + * with this property will have the property value set to the + * default provided. Any of the callback routines may be set + * to NULL if they are not needed. + * + * Zero-sized properties are allowed and do not store any data in + * the property list. These may be used as flags to indicate the + * presence or absence of a particular piece of information. The + * default pointer for a zero-sized property may be set to NULL. + * The property \p prp_create and \p prp_close callbacks are called for + * zero-sized properties, but the \p prp_set and \p prp_get callbacks + * are never called. + * + * The \p prp_create routine is called when a new property list with + * this property is being created. The #H5P_prp_create_func_t + * callback function is defined as #H5P_prp_cb1_t. + * + * The \p prp_create routine may modify the value to be set and those + * changes will be stored as the initial value of the property. + * If the \p prp_create routine returns a negative value, the new + * property value is not copied into the property and the + * \p prp_create routine returns an error value. + * + * The \p prp_set routine is called before a new value is copied into + * the property. The #H5P_prp_set_func_t callback function is defined + * as #H5P_prp_cb2_t. + * + * The \p prp_set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p prp_set routine returns a negative value, the new property + * value is not copied into the property and the \p prp_set routine + * returns an error value. The \p prp_set routine will not be called + * for the initial value; only the \p prp_create routine will be + * called. + * + * \b Note: The \p prp_set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p prp_get + * callback would then reverse the transformation or translation. + * A single \p prp_get or \p prp_set callback could handle multiple + * properties by performing different actions based on the property + * name or other properties in the property list. + * + * The \p prp_get routine is called when a value is retrieved from a + * property value. The #H5P_prp_get_func_t callback function is + * defined as #H5P_prp_cb2_t. + * + * The \p prp_get routine may modify the value to be returned from the + * query and those changes will be returned to the calling routine. + * If the \p prp_set routine returns a negative value, the query + * routine returns an error value. + * + * The \p prp_del routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as #H5P_prp_cb2_t. + * + * The \p prp_del routine may modify the value passed in, but the + * value is not used by the library when the \p prp_del routine + * returns. If the \p prp_del routine returns a negative value, + * the property list deletion routine returns an error value but + * the property is still deleted. + * + * The \p prp_copy routine is called when a new property list with + * this property is being created through a \p prp_copy operation. + * The #H5P_prp_copy_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If + * the \p prp_copy routine returns a negative value, the new + * property value is not copied into the property and the \p prp_copy + * routine returns an error value. + * + * The \p prp_close routine is called when a property list with this + * property is being closed. The #H5P_prp_close_func_t callback + * function is defined as #H5P_prp_cb1_t. + * + * The \p prp_close routine may modify the value passed in, but the + * value is not used by the library when the \p prp_close routine + * returns. If the \p prp_close routine returns a negative value, the + * property list close routine returns an error value but the property + * list is still closed. + * + * The #H5P_prp_cb1_t is as follows: + * \snippet this H5P_prp_cb1_t_snip + * + * The #H5P_prp_cb2_t is as follows: + * \snippet this H5P_prp_cb2_t_snip + * + * + * \cpp_c_api_note + * + */ /* Function prototypes */ -H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value, - H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, - 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); -H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, - H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, - H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, - H5P_prp_close_func_t prp_close); +H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value, + H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, + 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 + * + * \brief Registers a temporary property with a property list + * + * \plist_id + * \param[in] name Name of property to create + * \param[in] size Size of property in bytes + * \param[in] value Initial value for the property + * \param[in] prp_set Callback routine called before a new value is copied + * into the property's value + * \param[in] prp_get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_delete Callback routine called when a property is deleted + * from a property list + * \param[in] prp_copy Callback routine called when a property is copied + * from an existing property list + * \param[in] prp_close Callback routine called when a property list is + * being closed and the property value will be disposed + * of + * + * \return \herr_t + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pinsert2() or the macro H5Pinsert(). + * + * \details H5Pinsert1() creates a new property in a property + * list. The property will exist only in this property list and + * copies made from it. + * + * The initial property value must be provided in \p value and + * the property value will be set accordingly. + * + * The name of the property must not already exist in this list, + * or this routine will fail. + * + * The \p prp_set and \p prp_get callback routines may be set to NULL + * if they are not needed. + * + * Zero-sized properties are allowed and do not store any data + * in the property list. The default value of a zero-size + * property may be set to NULL. They may be used to indicate the + * presence or absence of a particular piece of information. + * + * The \p prp_set routine is called before a new value is copied + * into the property. The #H5P_prp_set_func_t callback function + * is defined as #H5P_prp_cb2_t. + * The \p prp_set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p prp_set routine returns a negative value, the new property + * value is not copied into the property and the \p set routine + * returns an error value. The \p prp_set routine will be called for + * the initial value. + * + * \b Note: The \p prp_set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p prp_get + * callback would then reverse the transformation or translation. + * A single \p prp_get or \p prp_set callback could handle multiple + * properties by performing different actions based on the + * property name or other properties in the property list. + * + * The \p prp_get routine is called when a value is retrieved from + * a property value. The #H5P_prp_get_func_t callback function + * is defined as #H5P_prp_cb2_t. + * + * The \p prp_get routine may modify the value to be returned from + * the query and those changes will be preserved. If the \p prp_get + * routine returns a negative value, the query routine returns + * an error value. + * + * The \p prp_delete routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as #H5P_prp_cb2_t. + * + * The \p prp_copy routine is called when a new property list with + * this property is being created through a \p prp_copy operation. + * The #H5P_prp_copy_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If the + * \p prp_copy routine returns a negative value, the new property value + * is not copied into the property and the prp_copy routine returns an + * error value. + * + * The \p prp_close routine is called when a property list with this + * property is being closed. + * The #H5P_prp_close_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_close routine may modify the value passed in, the + * value is not used by the library when the close routine + * returns. If the \p prp_close routine returns a negative value, + * the property list \p prp_close routine returns an error value + * but the property list is still closed. + * + * \b Note: There is no \p prp_create callback routine for temporary + * property list objects; the initial value is assumed to + * have any necessary setup already performed on it. + * + * The #H5P_prp_cb1_t is as follows: + * \snippet this H5P_prp_cb1_t_snip + * + * The #H5P_prp_cb2_t is as follows: + * \snippet this H5P_prp_cb2_t_snip + + * \cpp_c_api_note + */ +H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, + H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, + H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, + H5P_prp_close_func_t prp_close); +/** + * \ingroup DCPL + * + * \brief Returns information about a filter in a pipeline (DEPRECATED) + * + * + * + * \plist_id{plist_id} + * \param[in] filter Sequence number within the filter pipeline of + * the filter for which information is sought + * \param[out] flags Bit vector specifying certain general properties + * of the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * + * \return Returns the filter identifier if successful; Otherwise returns + * a negative value. See: #H5Z_filter_t + * + * \deprecated When was this function deprecated? + * + * \details H5Pget_filter1() returns information about a filter, specified + * by its filter number, in a filter pipeline, specified by the + * property list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p filter is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value + * if the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen + * bytes, the filter name will be copied into that array. The name + * will be null terminated if \p namelen is large enough. The + * filter name returned will be the name appearing in the file, the + * name registered for the filter, or an empty string. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.8.0 N-bit and scale-offset filters added. + * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and + * deprecated in this release. + * \version 1.6.4 \p filter parameter type changed to unsigned. + * + */ H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[]); -H5_DLL herr_t H5Pget_filter_by_id1(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[] /*out*/); +/** + * \ingroup DCPL + * + * \brief Returns information about the specified filter + * + * \plist_id{plist_id} + * \param[in] id Filter identifier + * \param[out] flags Bit vector specifying certain general properties + * of the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * + * + * \return Returns a non-negative value if successful; Otherwise returns + * a negative value. + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pget_filter_by_id2() or the macro H5Pget_filter_by_id(). + * + * \details H5Pget_filter_by_id1() returns information about a filter, specified + * in \p id, a filter identifier. + * + * \p plist_id must be a dataset or group creation property list and + * \p id must be in the associated filter pipeline. + * + * The \p id and \p flags parameters are used in the same + * manner as described in the discussion of H5Pset_filter(). + * + * Aside from the fact that they are used for output, the parameters + * \p cd_nelmts and \p cd_values[] are used in the same manner as + * described in the discussion of H5Pset_filter(). + * On input, the \p cd_nelmts parameter indicates the number of entries + * in the \p cd_values[] array allocated by the calling program; + * on exit it contains the number of values defined by the filter. + * + * On input, the \p namelen parameter indicates the number of + * characters allocated for the filter name by the calling program + * in the array \p name[]. On exit \p name[] contains the name of the + * filter with one character of the name in each element of the array. + * + * If the filter specified in \p id is not set for the property + * list, an error will be returned and this function will fail. + * + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.8.0 Function H5Pget_filter_by_id() renamed to + * H5Pget_filter_by_id1() and deprecated in this release. + * \version 1.6.0 Function introduced in this release. + */ +H5_DLL herr_t H5Pget_filter_by_id1(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, + size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, + char name[] /*out*/); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index b2bbee7..81ae514 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -22,15 +22,9 @@ #include "H5Gpublic.h" #include "H5Ipublic.h" -/* - * Reference types allowed. - */ -typedef enum { - H5R_BADTYPE = (-1), /*invalid Reference Type */ - H5R_OBJECT, /*Object reference */ - H5R_DATASET_REGION, /*Dataset Region Reference */ - H5R_MAXTYPE /*highest type (Invalid as true type) */ -} H5R_type_t; +/*****************/ +/* Public Macros */ +/*****************/ /* Note! Be careful with the sizes of the references because they should really * depend on the run-time values in the file. Unfortunately, the arrays need @@ -38,30 +32,277 @@ typedef enum { * for them. -QAK */ #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) -/* Object reference structure for user's code */ -typedef haddr_t hobj_ref_t; /* Needs to be large enough to store largest haddr_t in a worst case machine (ie. - 8 bytes currently) */ +/* 4 is used instead of sizeof(int) to permit portability between the Crays + * and other machines (the heap ID is always encoded as an int32 anyway). + */ #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) -/* 4 is used instead of sizeof(int) to permit portability between - the Crays and other machines (the heap ID is always encoded as an int32 anyway) -*/ -/* Dataset Region reference structure for user's code */ -typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE]; /* Buffer to store heap ID and index */ -/* Needs to be large enough to store largest haddr_t in a worst case machine (ie. 8 bytes currently) plus an - * int */ -/* Publicly visible data structures */ +/*******************/ +/* Public Typedefs */ +/*******************/ + +//! <!-- [H5R_type_t_snip] --> +/** + * Reference types allowed. + * + * \internal DO NOT CHANGE THE ORDER or VALUES as reference type values are + * encoded into the datatype message header. + */ +typedef enum { + H5R_BADTYPE = (-1), /**< Invalid reference type */ + H5R_OBJECT, /**< Object reference */ + H5R_DATASET_REGION, /**< Dataset Region Reference */ + H5R_MAXTYPE /**< Highest type (Invalid as true type) */ +} H5R_type_t; +//! <!-- [H5R_type_t_snip] --> + +//! <!-- [hobj_ref_t_snip] --> +/** + * Object reference structure for user's code + * This needs to be large enough to store largest haddr_t on a worst case + * machine (8 bytes currently). + */ +typedef haddr_t hobj_ref_t; +//! <!-- [hobj_ref_t_snip] --> + +//! <!-- [hdset_reg_ref_t_snip] --> +/** + * Dataset Region reference structure for user's code + * (Buffer to store heap ID and index) + * This needs to be large enough to store largest haddr_t in a worst case + * machine (8 bytes currently) plus an int + */ +typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE]; +//! <!-- [hdset_reg_ref_t_snip] --> + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ #ifdef __cplusplus extern "C" { #endif -/* Functions in H5R.c */ -H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); -H5_DLL hid_t H5Rdereference(hid_t dataset, H5R_type_t ref_type, const void *ref); -H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); -H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref, H5O_type_t *obj_type); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Creates a reference + * + * \param[out] ref Reference created by the function call + * \param[in] loc_id Location identifier used to locate the object being pointed to + * \param[in] name Name of object at location \p loc_id + * \param[in] ref_type Type of reference + * \param[in] space_id Dataspace identifier with selection. Used only for + * dataset region references; pass as -1 if reference is + * an object reference, i.e., of type #H5R_OBJECT + * + * \return \herr_t + * + * \details H5Rcreate() creates the reference, \p ref, of the type specified in + * \p ref_type, pointing to the object \p name located at \p loc_id. + * + * The HDF5 library maps the void type specified above for \p ref to + * the type specified in \p ref_type, which will be one of the following: + * \snippet this H5R_type_t_snip + * + * The parameters \p loc_id and \p name are used to locate the object. + * + * The parameter \p space_id identifies the dataset region that a + * dataset region reference points to. This parameter is used only with + * dataset region references and should be set to -1 if the reference + * is an object reference, #H5R_OBJECT. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Opens the HDF5 object referenced + * + * \obj_id + * \param[in] ref_type The reference type of \p ref + * \param[in] ref Reference to open + * + * \return Returns identifier of referenced object if successful; otherwise + * returns a negative value. + * + * \deprecated This function has been renamed from H5Rdereference() and is + * deprecated in favor of the macro H5Rdereference() or the function + * H5Rdereference2(). + * + * \details Given a reference, \p ref, to an object or a region in an object, + * H5Rdereference1() opens that object and returns an identifier. + * + * The parameter \p obj_id must be a valid identifier for an object in + * the HDF5 file containing the referenced object, including the file + * identifier. + * + * The parameter \p ref_type specifies the reference type of the + * reference \p ref. \p ref_type may contain either of the following + * values: + * - #H5R_OBJECT + * - #H5R_DATASET_REGION + * + * The object opened with this function should be closed when it is no + * longer needed so that resource leaks will not develop. Use the + * appropriate close function such as H5Oclose() or H5Dclose() for + * datasets. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Rdereference(hid_t dataset, H5R_type_t ref_type, const void *ref); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Sets up a dataspace and selection as specified by a region reference + * + * \param[in] dataset File identifier or identifier for any object in the file + * containing the referenced region + * \param[in] ref_type Reference type of \p ref, which must be #H5R_DATASET_REGION + * \param[in] ref Region reference to open + * + * \return Returns a valid dataspace identifier if successful; otherwise returns + * a negative value. + * + * \details H5Rget_region() creates a copy of the dataspace of the dataset + * pointed to by a region reference, \p ref, and defines a selection + * matching the selection pointed to by ref within the dataspace copy. + * + * \p dataset is used to identify the file containing the referenced + * region; it can be a file identifier or an identifier for any object + * in the file. + * + * The parameter \p ref_type specifies the reference type of \p ref and + * must contain the value #H5R_DATASET_REGION. + * + * Use H5Sclose() to release the dataspace identifier returned by this + * function when the identifier is no longer needed. + * + */ +H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of object that an object reference points to + * + * \param[in] id The dataset containing the reference object or the group + * containing that dataset + * \param[in] ref_type Type of reference to query + * \param[in] ref Reference to query + * \param[out] obj_type Type of referenced object + * + * \return \herr_t + * + * \details Given an object reference, \p ref, H5Rget_obj_type2() returns the + * type of the referenced object in \p obj_type. + * + * A \Emph{reference type} is the type of reference, either an object + * reference or a dataset region reference. An \Emph{object reference} + * points to an HDF5 object while a \Emph{dataset region reference} + * points to a defined region within a dataset. + * + * The \Emph{referenced object} is the object the reference points + * to. The \Emph{referenced object type}, or the type of the referenced + * object, is the type of the object that the reference points to. + * + * The location identifier, \p id, is the identifier for either the + * dataset containing the object reference or the group containing that + * dataset. + * + * Valid reference types, to pass in as \p ref_type, include the + * following: + * \snippet this H5R_type_t_snip + * + * If the application does not already know the object reference type, + * that can be determined with three preliminary calls: + * + * \li Call H5Dget_type() on the dataset containing the reference to + * get a datatype identifier for the dataset’s datatype. + * \li Using that datatype identifier, H5Tget_class() returns a datatype + * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can + * then be used to determine whether the reference’s datatype is + * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: + * - If the datatype is #H5T_STD_REF_OBJ, the reference object type + * is #H5R_OBJECT. + * - If the datatype is #H5T_STD_REF_DSETREG, the reference object + * type is #H5R_DATASET_REGION. + * + * When the function completes successfully, it returns one of the + * following valid object type values (defined in H5Opublic.h): + * \snippet H5Opublic.h H5O_type_t_snip + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref, H5O_type_t *obj_type); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves a name for a referenced object + * + * \param[in] loc_id Identifier for the file containing the reference or for + * any object in that file + * \param[in] ref_type Type of reference + * \param[in] ref An object or dataset region reference + * \param[out] name A buffer to place the name of the referenced object or + * dataset region. If \c NULL, then this call will return the + * size in bytes of the name. + * \param[in] size The size of the \p name buffer. When the size is passed in, + * the \c NULL terminator needs to be included. + * + * \return Returns the length of the name if successful, returning 0 (zero) if + * no name is associated with the identifier. Otherwise returns a + * negative value. + * + * \details H5Rget_name() retrieves a name for the object identified by \p ref.\n + * \p loc_id is used to identify the file containing the reference. It + * can be the file identifier for the file containing the reference or + * an identifier for any object in that file. + * + * \ref H5R_type_t is the reference type of \p ref. Valid values + * include the following: + * \snippet this H5R_type_t_snip + * + * \p ref is the reference for which the target object’s name is + * sought. + * + * If \p ref is an object reference, \p name will be returned with a + * name for the referenced object. If \p ref is a dataset region + * reference, \p name will contain a name for the object containing the + * referenced region. + * + * Up to \p size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of \p + * size, is unknown, a preliminary H5Rget_name() call can be made. The + * return value of this call will be the size of the object name. That + * value can then be assigned to \p size for a second H5Rget_name() + * call, which will retrieve the actual name. + * + * If there is no name associated with the object identifier or if the + * \p name is \c NULL, H5Rget_name() returns the size of the \p name + * buffer (the size does not include the \p NULL terminator). + * + * Note that an object in an HDF5 file may have multiple paths if there + * are multiple links pointing to it. This function may return any one + * of these paths. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name /*out*/, size_t size); @@ -72,7 +313,68 @@ H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, c #ifndef H5_NO_DEPRECATED_SYMBOLS /* Function prototypes */ -H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *_ref); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of object that an object reference points to + * + * \param[in] id The dataset containing the reference object or the group + * containing that dataset + * \param[in] ref_type Type of reference to query + * \param[in] ref Reference to query + * + * \return Returns a valid object type if successful; otherwise returns a + * negative value (#H5G_UNKNOWN). + * + * \deprecated This function has been renamed from H5Rget_obj_type() and is + * deprecated in favor of the macro H5Rget_obj_type() or the + * function H5Rget_obj_type2(). + * + * \details Given an object reference, \p ref, H5Rget_obj_type1() returns the + * type of the referenced object. + * + * A \Emph{reference type} is the type of reference, either an object + * reference or a dataset region reference. An \Emph{object reference} + * points to an HDF5 object while a \Emph{dataset region reference} + * points to a defined region within a dataset. + * + * The \Emph{referenced object} is the object the reference points + * to. The \Emph{referenced object type}, or the type of the referenced + * object, is the type of the object that the reference points to. + * + * The location identifier, \p id, is the identifier for either the + * dataset containing the object reference or the group containing that + * dataset. + * + * Valid reference types, to pass in as \p ref_type, include the + * following: + * \snippet this H5R_type_t_snip + * + * If the application does not already know the object reference type, + * that can be determined with three preliminary calls: + * + * \li Call H5Dget_type() on the dataset containing the reference to + * get a datatype identifier for the dataset’s datatype. + * \li Using that datatype identifier, H5Tget_class() returns a datatype + * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can + * then be used to determine whether the reference’s datatype is + * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: + * - If the datatype is #H5T_STD_REF_OBJ, the reference object type + * is #H5R_OBJECT. + * - If the datatype is #H5T_STD_REF_DSETREG, the reference object + * type is #H5R_DATASET_REGION. + * + * When the function completes successfully, it returns one of the + * following valid object type values (defined in H5Gpublic.h): + * \snippet H5Gpublic.h H5G_obj_t_snip + * + * \version 1.8.0 Function H5Rget_obj_type() renamed to H5Rget_obj_type1() and + * deprecated in this release. + * \since 1.6.0 + * + */ +H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Spublic.h b/src/H5Spublic.h index fb58843..7291c84 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -39,7 +39,7 @@ typedef enum H5S_class_t { /* Different ways of combining selections */ typedef enum H5S_seloper_t { H5S_SELECT_NOOP = -1, /* error */ - H5S_SELECT_SET = 0, /* Select "set" operation */ + H5S_SELECT_SET = 0, /* Select "set" operation */ H5S_SELECT_OR, /* Binary "or" operation for hyperslabs * (add new selection to existing selection) * Original region: AAAAAAAAAA @@ -77,57 +77,940 @@ typedef enum H5S_seloper_t { /* Enumerated type for the type of selection */ typedef enum { - H5S_SEL_ERROR = -1, /* Error */ - H5S_SEL_NONE = 0, /* Nothing selected */ - H5S_SEL_POINTS = 1, /* Points / elements selected */ + H5S_SEL_ERROR = -1, /* Error */ + H5S_SEL_NONE = 0, /* Nothing selected */ + H5S_SEL_POINTS = 1, /* Points / elements selected */ H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ - H5S_SEL_ALL = 3, /* Entire extent selected */ - H5S_SEL_N /*THIS MUST BE LAST */ + H5S_SEL_ALL = 3, /* Entire extent selected */ + H5S_SEL_N /*THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus extern "C" { #endif -/* Functions in H5S.c */ -H5_DLL hid_t H5Screate(H5S_class_t type); -H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); -H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); -H5_DLL hid_t H5Scopy(hid_t space_id); -H5_DLL herr_t H5Sclose(hid_t space_id); -H5_DLL herr_t H5Sencode(hid_t obj_id, void *buf, size_t *nalloc); -H5_DLL hid_t H5Sdecode(const void *buf); +/* Operations on dataspaces */ +/** + * \ingroup H5S + * + * \brief Releases and terminates access to a dataspace + * + * \space_id + * + * \return \herr_t + * + * \details H5Sclose() releases a dataspace. Further access through the + * dataspace identifier is illegal. Failure to release a dataspace with this + * call will result in resource leaks. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sclose(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Creates an exact copy of a dataspace + * + * \space_id + * + * \return \hid_tv{dataspace} + * + * \details H5Scopy() creates a new dataspace which is an exact copy of the + * dataspace identified by \p space_id. The dataspace identifier + * returned from this function should be released with H5Sclose() + * or resource leaks will occur. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Scopy(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Creates a new dataspace of a specified type + * + * \param[in] type Type of dataspace to be created + * + * \return \hid_t{dataspace} + * + * \details H5Screate() creates a new dataspace of a particular type. Currently + * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL. + * + * Further dataspace types may be added later. + * + * A scalar dataspace, #H5S_SCALAR, has a single element, though that + * element may be of a complex datatype, such as a compound or array + * datatype. By convention, the rank of a scalar dataspace is always \p 0 + * (zero); think of it geometrically as a single, dimensionless point, + * though that point can be complex. + * + * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements. + * + * A null dataspace, #H5S_NULL, has no data elements. + * + * The dataspace identifier returned by this function can be released with + * H5Sclose() so that resource leaks will not occur. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Screate(H5S_class_t type); +/** + * \ingroup H5S + * \brief Creates a new simple dataspace and opens it for access + * + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims Array specifying the size of each dimension + * \param[in] maxdims Array specifying the maximum size of each dimension + * + * \return \hid_t{dataspace} + * + * \details H5Screate_simple() creates a new simple dataspace and opens it + * for access, returning a dataspace identifier. + * + * \p rank is the number of dimensions used in the dataspace. + * + * \p dims is a one-dimensional array of size rank specifying the + * size of each dimension of the dataset. \p maxdims is an array of + * the same size specifying the upper limit on the size of each + * dimension. + * + * Any element of \p dims can be \p 0 (zero). Note that no data can + * be written to a dataset if the size of any dimension of its current + * dataspace is \p 0. This is sometimes a useful initial state for + * a dataset. + * + * \p maxdims may be the null pointer, in which case the upper limit + * is the same as \p dims. Otherwise, no element of \p maxdims + * should be smaller than the corresponding element of \p dims. + * + * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of + * the corresponding dimension is unlimited. + * + * Any dataset with an unlimited dimension must also be chunked; see + * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims + * does not equal \p maxdims. + * + * The dataspace identifier returned from this function must be + * released with H5Sclose() or resource leaks will occur. + * + * \note Once a dataspace has been created, specific regions or elements in + * the dataspace can be selected and selections can be removed, as well. + * For example, H5Sselect_hyperslab() selects a region in a dataspace and + * H5Sselect_elements() selects array elements in a dataspace. These + * functions are used for subsetting. H5Sselect_none() removes all + * selections from a dataspace and is used in Parallel HDF5 when a process + * does not have or need to write data. + * + * \version 1.4.0 Fortran subroutine introduced. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); +/** + * \ingroup H5S + * + * \brief Decodes a binary object description of data space and returns a + * new object handle + * + * \param[in] buf Buffer for the data space object to be decoded + * + * \return \hid_t{dataspace} + * + * \details Given an object description of a dataspace in binary in a + * buffer, H5Sdecode() reconstructs the HDF5 data type object and + * returns a new object handle for it. The binary description of the + * object is encoded by H5Sencode(). The user is responsible for + * passing in the right buffer. The types of dataspace addressed + * in this function are null, scalar, and simple space. For a + * simple dataspace, the selection information (for example, + * hyperslab selection) is also encoded and decoded. A complex + * dataspace has not been implemented in the library. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Sdecode(const void *buf); +/** + * \ingroup H5S + * + * \brief Encodes a data space object description into a binary buffer + * + * \space_id{obj_id} + * \param[in,out] buf Buffer for the object to be encoded into; + * If the provided buffer is NULL, only the size of + * buffer needed is returned through \p nalloc. + * \param[in,out] nalloc The size of the allocated buffer + * + * \return \herr_t + * + * \details Given the data space identifier \p obj_id, H5Sencode() converts + * a data space description into binary form in a buffer. Using + * this binary form in the buffer, a data space object can be + * reconstructed using H5Sdecode() to return a new object handle + * (\p hid_t) for this data space. + * + * A preliminary H5Sencode() call can be made to find out the size + * of the buffer needed. This value is returned as \p nalloc. That + * value can then be assigned to \p nalloc for a second H5Sencode1() + * call, which will retrieve the actual encoded object. + * + * If the library finds out \p nalloc is not big enough for the + * object, it simply returns the size of the buffer needed through + * \p nalloc without encoding the provided buffer. + * + * The types of data space addressed in this function are null, + * scalar, and simple space. For a simple data space, the information + * on the selection, for example, hyperslab selection, is also + * encoded and decoded. A complex data space has not been + * implemented in the library. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Sencode(hid_t obj_id, void *buf, size_t *nalloc); +/** + * \ingroup H5S + * + * \brief Copies the extent of a dataspace + * + * \space_id{dst_id} + * \space_id{src_id} + * + * \return \herr_t + * + * \details H5Sextent_copy() copies the extent from \p src_id to \p dst_id. + * This action may change the type of the dataspace. + * + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id); +/** + * \ingroup H5S + * + * \brief Determines whether two dataspace extents are equal + * + * \space_id{space1_id} + * \space_id{space2_id} + * + * \return \htri_t + * + * \details H5Sextent_equal() determines whether the dataspace extents of + * two dataspaces, \p space1_id and \p space2_id, are equal. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Sextent_equal(hid_t space1_id, hid_t space2_id); +/** + * \ingroup H5S + * + * \brief Retrieves dataspace dimension size and maximum size + * + * \space_id + * \param[out] dims Pointer to array to store the size of each dimension + * \param[out] maxdims Pointer to array to store the maximum size of each + * dimension + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_dims() returns the size and maximum sizes + * of each dimension of a dataspace \p space_id through the \p dims + * and \p maxdims parameters. + * + * Either or both of \p dims and \p maxdims may be NULL. + * + * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), + * the maximum size of that dimension is unlimited. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); +/** + * \ingroup H5S + * + * \brief Determines the dimensionality of a dataspace + * + * \space_id + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_ndims() determines the dimensionality (or + * rank) of a dataspace. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Determines the number of elements in a dataspace + * + * \space_id + * + * \return Returns the number of elements in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_npoints() determines the number of elements + * in a dataspace \p space_id. For example, a simple 3-dimensional + * dataspace with dimensions 2, 3, and 4 would have 24 elements. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); -H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); -H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); -H5_DLL htri_t H5Sis_simple(hid_t space_id); -H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); -H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], - const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); +/** + * \ingroup H5S + * + * \brief Determines the current class of a dataspace + * + * \space_id + * + * \return Returns a dataspace class name if successful; + * otherwise #H5S_NO_CLASS (-1). + * + * \details H5Sget_simple_extent_type() determines the current class of a + * dataspace \p space_id. + * + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Determines whether a dataspace is a simple dataspace + * + * \space_id + * + * \return \htri_t + * + * \details H5Sis_simple() determines whether or not a dataspace is a simple + * dataspace. + * + * \note Currently, all dataspace objects are simple dataspaces; complex + * dataspace support will be added in the future. + * + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL htri_t H5Sis_simple(hid_t space_id); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Resets the extent of a dataspace back to "none" + * + * \space_id + * + * \return \herr_t + * + * \details H5Sset_extent_none() resets the type of a dataspace to + * #H5S_NULL with no extent information stored for the dataspace. + * + * \version 1.10.7 To set the class to #H5S_NO_CLASS. + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sset_extent_none(hid_t space_id); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Sets or resets the size of an existing dataspace + * + * \space_id + * \param[in] rank Rank, or dimensionality, of the dataspace + * \param[in] dims Array containing current size of dataspace + * \param[in] max Array containing maximum size of dataspace + * + * \return \herr_t + * + * \details H5Sset_extent_simple() sets or resets the size of an existing + * dataspace. + * + * \p rank is the dimensionality, or number of dimensions, of the + * dataspace. + * + * \p dims is an array of size \p rank which contains the new size + * of each dimension in the dataspace. \p max is an array of size + * \p rank which contains the maximum size of each dimension in + * the dataspace. + * + * Any previous extent is removed from the dataspace, the dataspace + * type is set to #H5S_SIMPLE, and the extent is set as specified. + * + * Note that a dataset must be chunked if \p dims does not equal + * \p max. + * + * + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); + /* #define NEW_HYPERSLAB_API */ #ifdef NEW_HYPERSLAB_API -H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], - const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); -H5_DLL herr_t H5Sselect_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); -H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); + +/* Operations on dataspace selections */ +/** + * \ingroup H5S + * + * \brief Performs an operation on a hyperslab and an existing selection and + * returns the resulting selection + * + * \space_id + * \param[in] op Operation to perform on the current selection + * \param[in] start Offset of the start of of the hyperslab + * \param[in] stride Hyperslab stride + * \param[in] count Number of blocks included in the hyperslab + * \param[in] block Size of a block in the hyperslab + * + * \return \hid_tv{dataspace} + * + * \details H5Scombine_hyperslab() combines a hyperslab selection specified + * by \p start, \p stride, \p count and \p block with the current + * selection for the dataspace \p space_id, creating a new dataspace + * to return the generated selection. If the current selection is + * not a hyperslab, it is freed and the hyperslab parameters passed + * in are combined with the #H5S_SEL_ALL hyperslab (ie. a selection + * composing the entire current extent). If either \p stride or + * \p block is NULL, then it will be set to \p 1. + * + * \since 1.10.6 + * + */ +H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], + const hsize_t stride[], const hsize_t count[], const hsize_t block[]); +/** + * \ingroup H5S + * + * \brief Combine two hyperslab selections with an operation, returning a + * dataspace with the resulting selection + * + * \space_id{space1_id} + * \param[in] op Selection operator + * \space_id{space2_id} + * + * \return \hid_t{dataspace} + * + * \details H5Scombine_select() combines two hyperslab selections + * \p space1_id and \p space2_id with an operation, returning a + * new dataspace with the resulting selection. The dataspace extent + * from \p space1_id is copied for the dataspace extent of the + * newly created dataspace. + * + * \since 1.10.6 + * + */ +H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); #endif /* NEW_HYPERSLAB_API */ -H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord); -H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); -H5_DLL herr_t H5Sset_extent_none(hid_t space_id); -H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id); -H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2); -H5_DLL herr_t H5Sselect_all(hid_t spaceid); -H5_DLL herr_t H5Sselect_none(hid_t spaceid); -H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset); -H5_DLL htri_t H5Sselect_valid(hid_t spaceid); -H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid); -H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); -H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, - hsize_t buf[/*numblocks*/]); -H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, - hsize_t buf[/*numpoints*/]); -H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]); +/** + * \ingroup H5S + * + * \brief Gets the bounding box containing the current selection + * + * \space_id{spaceid} + * \param[out] start Starting coordinates of the bounding box + * \param[out] end Ending coordinates of the bounding box, i.e., the + * coordinates of the diagonally opposite corner + * + * \return \herr_t + * + * \details H5Sget_select_bounds() retrieves the coordinates of the bounding + * box containing the current selection and places them into + * user-supplied buffers. + * + * The \p start and \p end buffers must be large enough to hold + * the dataspace rank number of coordinates. + * + * The bounding box exactly contains the selection. I.e., if a + * 2-dimensional element selection is currently defined as containing + * the points (4,5), (6,8), and (10,7), then the bounding box + * will be (4, 5), (10, 8). + * + * The bounding box calculation includes the current offset of the + * selection within the dataspace extent. + * + * Calling this function on a \a none selection will fail. + * + * \version 1.6.0 The \p start and \p end parameters have changed from type + * \p hsize_t * to \p hssize_t *. + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]); +/** + * \ingroup H5S + * + * \brief Gets the number of element points in the current selection + * + * \space_id{spaceid} + * + * \return Returns the number of element points in the current dataspace + * selection if successful. Otherwise returns a negative value. + * + * \details H5Sget_select_elem_npoints() returns the number of element + * points in the current dataspace selection, so that the element + * points can be retrieved with H5Sget_select_elem_pointlist(). + * (This is similar to the way that H5Sget_select_hyper_nblocks() + * and H5Sget_select_hyper_blocklist() work with hyperslab + * selections.) + * + * Coincidentally, H5Sget_select_npoints() and + * H5Sget_select_elem_npoints() will always return the same value + * when an element selection is queried, but + * H5Sget_select_elem_npoints() does not work with other selection + * types. + * + * \since 1.2.0 + * + */ +H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); +/** + * \ingroup H5S + * + * \brief Gets the list of element points currently selected + * + * \space_id{spaceid} + * \param[in] startpoint Element point to start with + * \param[in] numpoints Number of element points to get + * \param[out] buf List of element points selected + * + * \details H5Sget_select_elem_pointlist() returns the list of element + * points in the current dataspace selection \p space_id. Starting + * with the \p startpoint in the list of points, \p numpoints + * points are put into the user's buffer. If the user's buffer + * fills up before \p numpoints points are inserted, the buffer + * will contain only as many points as fit. + * + * The element point coordinates have the same dimensionality + * (rank) as the dataspace they are located within. The list of + * element points is formatted as follows:\n + * \<coordinate\>, followed by\n + * the next coordinate,\n + * etc.\n + * until all of the selected element points have been listed. + * + * The points are returned in the order they will be iterated + * through when the selection is read/written from/to disk. + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, + hsize_t buf[/*numpoints*/]); +/** + * \ingroup H5S + * + * \brief Gets the list of hyperslab blocks currently selected + * + * \space_id{spaceid} + * \param[in] startblock Hyperslab block to start with + * \param[in] numblocks Number of hyperslab blocks to get + * \param[out] buf List of hyperslab blocks selected + * + * \return \herr_t + * + * \details H5Sget_select_hyper_blocklist() returns a list of the hyperslab + * blocks currently selected. Starting with the \p startblock-th block + * in the list of blocks, \p numblocks blocks are put into the + * user's buffer. If the user's buffer fills up before \p numblocks + * blocks are inserted, the buffer will contain only as many blocks + * as fit. + * + * The block coordinates have the same dimensionality (rank) as the + * dataspace they are located within. The list of blocks is + * formatted as follows:\n + * \<"start" coordinate\>, immediately followed by\n + * \<"opposite" corner coordinate\>, followed by\n + * the next "start" and "opposite" coordinates,\n + * etc. until all of the selected blocks have been listed.\n + * No guarantee of any order of the blocks is implied. + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, + hsize_t buf[/*numblocks*/]); +/** + * \ingroup H5S + * + * \brief Get number of hyperslab blocks + * + * \space_id{spaceid} + * + * \return Returns the number of hyperslab blocks in the current dataspace + * selection if successful. Otherwise returns a negative value. + * + * \details H5Sget_select_hyper_nblocks() returns the number of hyperslab + * blocks in the current dataspace selection. + * + * \since 1.2.0 + * + */ +H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid); +/** + * \ingroup H5S + * + * \brief Determines the number of elements in a dataspace selection + * + * \space_id{spaceid} + * + * \return Returns the number of elements in the selection if successful; + * otherwise returns a negative value. + * + * \details H5Sget_select_npoints() determines the number of elements in + * the current selection of a dataspace. It works with any + * selection type, and is the correct way to retrieve the number + * of elements in a selection. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); +/** + * \ingroup H5S + * + * \brief Determines the type of the dataspace selection + * + * \space_id{spaceid} + * + * \return Returns the dataspace selection type, a value of the enumerated + * datatype #H5S_sel_type, if successful. + * + * \details H5Sget_select_type() retrieves the type of dataspace selection + * currently defined for the dataspace \p space_id. Valid values + * for the dataspace selection type are: + * + * <table> + * <tr> + * <td>#H5S_SEL_NONE</td> + * <td>No selection is defined</td> + * </tr> + * <tr> + * <td>#H5S_SEL_POINTS</td> + * <td>A sequence of points is selected</td> + * </tr> + * <tr> + * <td>#H5S_SEL_HYPERSLABS</td> + * <td>A hyperslab or compound hyperslab is selected</td> + * </tr> + * <tr> + * <td>#H5S_SEL_ALL</td> + * <td>The entire dataset is selected</td> + * </tr> + * </table> + * + * Otherwise returns a negative value. + * + * \since 1.6.0 + * + */ H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); +/** + * \ingroup H5S + * + * \brief Sets the offset of a simple dataspace + * + * \space_id + * \param[in] offset The offset at which to position the selection + * + * \return \herr_t + * + * \details H5Soffset_simple() sets the offset of a simple dataspace + * \p space_id. The offset array must be the same number of + * elements as the number of dimensions for the dataspace. If the + * \p offset array is set to NULL, the offset for the dataspace is + * reset to 0. + * + * This function allows the same shaped selection to be moved to + * different locations within a dataspace without requiring it to + * be redefined. + * + * \version 1.4.0 Fortran subroutine was introduced. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset); +/** + * \ingroup H5S + * + * \brief Selects an entire dataspace + * + * \space_id{spaceid} + * + * \return \herr_t + * + * \details H5Sselect_all() selects the entire extent of the dataspace + * \p dspace_id. + * + * More specifically, H5Sselect_all() sets the selection type to + * #H5S_SEL_ALL, which specifies the entire dataspace anywhere it + * is applied. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_all(hid_t spaceid); +/** + * \ingroup H5S + * + * \brief Selects array elements to be included in the selection for a + * dataspace + * + * \space_id + * \param[in] op Operator specifying how the new selection is to be + * combined with the existing selection for the dataspace + * \param[in] num_elem Number of elements to be selected + * \param[in] coord A pointer to a buffer containing a serialized copy of + * a 2-dimensional array of zero-based values specifying + * the coordinates of the elements in the point selection + * + * \return \herr_t + * + * \details H5Sselect_elements() selects array elements to be included in + * the selection for the \p space_id dataspace. This is referred + * to as a point selection. + * + * The number of elements selected is set in the \p num_elements + * parameter. + * + * The \p coord parameter is a pointer to a buffer containing a + * serialized 2-dimensional array of size \p num_elements by the + * rank of the dataspace. The array lists dataset elements in the + * point selection; that is, it’s a list of of zero-based values + * specifying the coordinates in the dataset of the selected + * elements. The order of the element coordinates in the \p coord + * array specifies the order in which the array elements are + * iterated through when I/O is performed. Duplicate coordinate + * locations are not checked for. See below for examples of the + * mapping between the serialized contents of the buffer and the + * point selection array that it represents. + * + * The selection operator \p op determines how the new selection + * is to be combined with the previously existing selection for + * the dataspace. The following operators are supported: + * + * <table> + * <tr> + * <td>#H5S_SELECT_SET</td> + * <td>Replaces the existing selection with the parameters from + * this call. Overlapping blocks are not supported with this + * operator. Adds the new selection to the existing selection. + * </td> + * </tr> + * <tr> + * <td>#H5S_SELECT_APPEND</td> + * <td>Adds the new selection following the last element of the + * existing selection.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_PREPEND</td> + * <td>Adds the new selection preceding the first element of the + * existing selection.</td> + * </tr> + * </table> + * + * <b>Mapping the serialized \p coord buffer to a 2-dimensional + * point selection array:</b> + * To illustrate the construction of the contents of the \p coord + * buffer, consider two simple examples: a selection of 5 points in + * a 1-dimensional array and a selection of 3 points in a + * 4-dimensional array. + * + * In the 1D case, we will be selecting five points and a 1D + * dataspace has rank 1, so the selection will be described in a + * 5-by-1 array. To select the 1st, 14th, 17th, 23rd, 8th elements + * of the dataset, the selection array would be as follows + * (remembering that point coordinates are zero-based): + * \n 0 + * \n 13 + * \n 16 + * \n 22 + * \n 7 + * + * This point selection array will be serialized in the \p coord + * buffer as: + * \n 0 13 16 22 7 + * + * In the 4D case, we will be selecting three points and a 4D + * dataspace has rank 4, so the selection will be described in a + * 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and + * (8,22,30,22), the point selection array would be as follows: + * \n 0 0 0 0 + * \n 13 5 11 17 + * \n 7 21 29 21 + * + * This point selection array will be serialized in the \p coord + * buffer as: + * \n 0 0 0 0 13 5 11 17 7 21 29 21 + * + * \version 1.6.4 C coord parameter type changed to \p const hsize_t. + * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T). + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord); +/** + * \ingroup H5S + * + * \brief Selects a hyperslab region to add to the current selected region + * + * \space_id + * \param[in] op Operation to perform on current selection + * \param[in] start Offset of start of hyperslab + * \param[in] stride Hyperslab stride + * \param[in] count Number of blocks included in hyperslab + * \param[in] block Size of block in hyperslab + * + * \return \herr_t + * + * \details H5Sselect_hyperslab() selects a hyperslab region to add to the + * current selected region for the dataspace specified by + * \p space_id. + * + * The \p start, \p stride, \p count, and \p block arrays must be the + * same size as the rank of the dataspace. For example, if the + * dataspace is 4-dimensional, each of these parameters must be a + * 1-dimensional array of size 4. + * + * The selection operator \p op determines how the new selection + * is to be combined with the already existing selection for the + * dataspace. The following operators are supported: + * + * <table> + * <tr> + * <td>#H5S_SELECT_SET</td> + * <td>Replaces the existing selection with the + * parameters from this call. Overlapping blocks + * are not supported with this operator.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_OR</td> + * <td>Adds the new selection to the existing selection. + * (Binary OR)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_AND</td> + * <td>Retains only the overlapping portions of the + * new selection and the existing selection. + * (Binary AND)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_XOR</td> + * <td>Retains only the elements that are members of + * the new selection or the existing selection, + * excluding elements that are members of both + * selections. (Binary exclusive-OR, XOR) + * </td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTB</td> + * <td>Retains only elements of the existing selection + * that are not in the new selection.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTA</td> + * <td>Retains only elements of the new selection that + * are not in the existing selection.</td> + * </tr> + * </table> + * + * The \p start array specifies the offset of the starting element + * of the specified hyperslab. + * + * The \p stride array chooses array locations from the dataspace with + * each value in the \p stride array determining how many elements to + * move in each dimension. Setting a value in the \p stride array to + * \p 1 moves to each element in that dimension of the dataspace; + * setting a value of \p 2 in allocation in the \p stride array moves + * to every other element in that dimension of the dataspace. In + * other words, the \p stride determines the number of elements to + * move from the \p start location in each dimension. Stride values + * of \p 0 are not allowed. If the \p stride parameter is NULL, a + * contiguous hyperslab is selected (as if each value in the \p stride + * array were set to \p 1). + * + * The \p count array determines how many blocks to select from the + * dataspace, in each dimension. + * + * The \p block array determines the size of the element block + * selected from the dataspace. If the \p block parameter is set to + * NULL, the block size defaults to a single element in each dimension + * (as if each value in the \p block array were set to \p 1). + * + * For example, consider a 2-dimensional dataspace with hyperslab + * selection settings as follows: the \p start offset is specified as + * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2]. + * In C, these settings will specify a hyperslab consisting of 21 + * 2x2 blocks of array elements starting with location (1,1) with the + * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; + * in Fortran, they will specify a hyperslab consisting of 21 2x2 + * blocks of array elements starting with location (2,2) with the + * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. + * + * Regions selected with this function call default to C order + * iteration when I/O is performed. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], + const hsize_t stride[], const hsize_t count[], const hsize_t block[]); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Resets the selection region to include no elements + * + * \space_id{spaceid} + * + * \return \herr_t + * + * \details H5Sselect_none() resets the selection region for the dataspace + * \p space_id to include no elements. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_none(hid_t spaceid); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Verifies that the selection is within the extent of the dataspace + * + * \space_id{spaceid} + * + * \return \htri_t + * + * \details H5Sselect_valid() verifies that the selection for the dataspace + * \p space_id is within the extent of the dataspace if the current + * offset for the dataspace is used. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL htri_t H5Sselect_valid(hid_t spaceid); #ifdef __cplusplus } diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index 33c71b9..b34138b 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -23,212 +23,300 @@ #define HOFFSET(S, M) (offsetof(S, M)) -/* These are the various classes of datatypes */ -/* If this goes over 16 types (0-15), the file format will need to change) */ +/** + * These are the various classes of datatypes + * internal If this goes over 16 types (0-15), the file format will need to + * change. + */ +//! <!-- [H5T_class_t_snip] --> typedef enum H5T_class_t { - H5T_NO_CLASS = -1, /*error */ - H5T_INTEGER = 0, /*integer types */ - H5T_FLOAT = 1, /*floating-point types */ - H5T_TIME = 2, /*date and time types */ - H5T_STRING = 3, /*character string types */ - H5T_BITFIELD = 4, /*bit field types */ - H5T_OPAQUE = 5, /*opaque types */ - H5T_COMPOUND = 6, /*compound types */ - H5T_REFERENCE = 7, /*reference types */ - H5T_ENUM = 8, /*enumeration types */ - H5T_VLEN = 9, /*Variable-Length types */ - H5T_ARRAY = 10, /*Array types */ - - H5T_NCLASSES /*this must be last */ + H5T_NO_CLASS = -1, /**< error */ + H5T_INTEGER = 0, /**< integer types */ + H5T_FLOAT = 1, /**< floating-point types */ + H5T_TIME = 2, /**< date and time types */ + H5T_STRING = 3, /**< character string types */ + H5T_BITFIELD = 4, /**< bit field types */ + H5T_OPAQUE = 5, /**< opaque types */ + H5T_COMPOUND = 6, /**< compound types */ + H5T_REFERENCE = 7, /**< reference types */ + H5T_ENUM = 8, /**< enumeration types */ + H5T_VLEN = 9, /**< variable-Length types */ + H5T_ARRAY = 10, /**< array types */ + + H5T_NCLASSES /**< sentinel: this must be last */ } H5T_class_t; +//! <!-- [H5T_class_t_snip] --> -/* Byte orders */ +/** + * Byte orders + */ +//! <!-- [H5T_order_t_snip] --> typedef enum H5T_order_t { - H5T_ORDER_ERROR = -1, /*error */ - H5T_ORDER_LE = 0, /*little endian */ - H5T_ORDER_BE = 1, /*bit endian */ - H5T_ORDER_VAX = 2, /*VAX mixed endian */ - H5T_ORDER_MIXED = 3, /*Compound type with mixed member orders */ - H5T_ORDER_NONE = 4 /*no particular order (strings, bits,..) */ + H5T_ORDER_ERROR = -1, /**< error */ + H5T_ORDER_LE = 0, /**< little endian */ + H5T_ORDER_BE = 1, /**< bit endian */ + H5T_ORDER_VAX = 2, /**< VAX mixed endian */ + H5T_ORDER_MIXED = 3, /**< Compound type with mixed member orders */ + H5T_ORDER_NONE = 4 /**< no particular order (strings, bits,..) */ /*H5T_ORDER_NONE must be last */ } H5T_order_t; +//! <!-- [H5T_order_t_snip] --> -/* Types of integer sign schemes */ +/** + * Types of integer sign schemes + */ +//! <!-- [H5T_sign_t_snip] --> typedef enum H5T_sign_t { - H5T_SGN_ERROR = -1, /*error */ - H5T_SGN_NONE = 0, /*this is an unsigned type */ - H5T_SGN_2 = 1, /*two's complement */ + H5T_SGN_ERROR = -1, /**< error */ + H5T_SGN_NONE = 0, /**< this is an unsigned type */ + H5T_SGN_2 = 1, /**< two's complement */ - H5T_NSGN = 2 /*this must be last! */ + H5T_NSGN = 2 /** sentinel: this must be last! */ } H5T_sign_t; +//! <!-- [H5T_sign_t_snip] --> -/* Floating-point normalization schemes */ +/** + * Floating-point normalization schemes + */ +//! <!-- [H5T_norm_t_snip] --> typedef enum H5T_norm_t { - H5T_NORM_ERROR = -1, /*error */ - H5T_NORM_IMPLIED = 0, /*msb of mantissa isn't stored, always 1 */ - H5T_NORM_MSBSET = 1, /*msb of mantissa is always 1 */ - H5T_NORM_NONE = 2 /*not normalized */ + H5T_NORM_ERROR = -1, /**< error */ + H5T_NORM_IMPLIED = 0, /**< msb of mantissa isn't stored, always 1 */ + H5T_NORM_MSBSET = 1, /**< msb of mantissa is always 1 */ + H5T_NORM_NONE = 2 /**< not normalized */ /*H5T_NORM_NONE must be last */ } H5T_norm_t; +//! <!-- [H5T_norm_t_snip] --> -/* - * Character set to use for text strings. Do not change these values since - * they appear in HDF5 files! +/** + * Character set to use for text strings. + * \internal Do not change these values since they appear in HDF5 files! */ typedef enum H5T_cset_t { - H5T_CSET_ERROR = -1, /*error */ - H5T_CSET_ASCII = 0, /*US ASCII */ - H5T_CSET_UTF8 = 1, /*UTF-8 Unicode encoding */ - H5T_CSET_RESERVED_2 = 2, /*reserved for later use */ - H5T_CSET_RESERVED_3 = 3, /*reserved for later use */ - H5T_CSET_RESERVED_4 = 4, /*reserved for later use */ - H5T_CSET_RESERVED_5 = 5, /*reserved for later use */ - H5T_CSET_RESERVED_6 = 6, /*reserved for later use */ - H5T_CSET_RESERVED_7 = 7, /*reserved for later use */ - H5T_CSET_RESERVED_8 = 8, /*reserved for later use */ - H5T_CSET_RESERVED_9 = 9, /*reserved for later use */ - H5T_CSET_RESERVED_10 = 10, /*reserved for later use */ - H5T_CSET_RESERVED_11 = 11, /*reserved for later use */ - H5T_CSET_RESERVED_12 = 12, /*reserved for later use */ - H5T_CSET_RESERVED_13 = 13, /*reserved for later use */ - H5T_CSET_RESERVED_14 = 14, /*reserved for later use */ - H5T_CSET_RESERVED_15 = 15 /*reserved for later use */ + H5T_CSET_ERROR = -1, /**< error */ + H5T_CSET_ASCII = 0, /**< US ASCII */ + H5T_CSET_UTF8 = 1, /**< UTF-8 Unicode encoding */ + H5T_CSET_RESERVED_2 = 2, /**< reserved for later use */ + H5T_CSET_RESERVED_3 = 3, /**< reserved for later use */ + H5T_CSET_RESERVED_4 = 4, /**< reserved for later use */ + H5T_CSET_RESERVED_5 = 5, /**< reserved for later use */ + H5T_CSET_RESERVED_6 = 6, /**< reserved for later use */ + H5T_CSET_RESERVED_7 = 7, /**< reserved for later use */ + H5T_CSET_RESERVED_8 = 8, /**< reserved for later use */ + H5T_CSET_RESERVED_9 = 9, /**< reserved for later use */ + H5T_CSET_RESERVED_10 = 10, /**< reserved for later use */ + H5T_CSET_RESERVED_11 = 11, /**< reserved for later use */ + H5T_CSET_RESERVED_12 = 12, /**< reserved for later use */ + H5T_CSET_RESERVED_13 = 13, /**< reserved for later use */ + H5T_CSET_RESERVED_14 = 14, /**< reserved for later use */ + H5T_CSET_RESERVED_15 = 15 /**< reserved for later use */ } H5T_cset_t; #define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined */ -/* - * Type of padding to use in character strings. Do not change these values - * since they appear in HDF5 files! +/** + * Type of padding to use in character strings. + * \internal Do not change these values since they appear in HDF5 files! */ typedef enum H5T_str_t { - H5T_STR_ERROR = -1, /*error */ - H5T_STR_NULLTERM = 0, /*null terminate like in C */ - H5T_STR_NULLPAD = 1, /*pad with nulls */ - H5T_STR_SPACEPAD = 2, /*pad with spaces like in Fortran */ - H5T_STR_RESERVED_3 = 3, /*reserved for later use */ - H5T_STR_RESERVED_4 = 4, /*reserved for later use */ - H5T_STR_RESERVED_5 = 5, /*reserved for later use */ - H5T_STR_RESERVED_6 = 6, /*reserved for later use */ - H5T_STR_RESERVED_7 = 7, /*reserved for later use */ - H5T_STR_RESERVED_8 = 8, /*reserved for later use */ - H5T_STR_RESERVED_9 = 9, /*reserved for later use */ - H5T_STR_RESERVED_10 = 10, /*reserved for later use */ - H5T_STR_RESERVED_11 = 11, /*reserved for later use */ - H5T_STR_RESERVED_12 = 12, /*reserved for later use */ - H5T_STR_RESERVED_13 = 13, /*reserved for later use */ - H5T_STR_RESERVED_14 = 14, /*reserved for later use */ - H5T_STR_RESERVED_15 = 15 /*reserved for later use */ + H5T_STR_ERROR = -1, /**< error */ + H5T_STR_NULLTERM = 0, /**< null terminate like in C */ + H5T_STR_NULLPAD = 1, /**< pad with nulls */ + H5T_STR_SPACEPAD = 2, /**< pad with spaces like in Fortran */ + H5T_STR_RESERVED_3 = 3, /**< reserved for later use */ + H5T_STR_RESERVED_4 = 4, /**< reserved for later use */ + H5T_STR_RESERVED_5 = 5, /**< reserved for later use */ + H5T_STR_RESERVED_6 = 6, /**< reserved for later use */ + H5T_STR_RESERVED_7 = 7, /**< reserved for later use */ + H5T_STR_RESERVED_8 = 8, /**< reserved for later use */ + H5T_STR_RESERVED_9 = 9, /**< reserved for later use */ + H5T_STR_RESERVED_10 = 10, /**< reserved for later use */ + H5T_STR_RESERVED_11 = 11, /**< reserved for later use */ + H5T_STR_RESERVED_12 = 12, /**< reserved for later use */ + H5T_STR_RESERVED_13 = 13, /**< reserved for later use */ + H5T_STR_RESERVED_14 = 14, /**< reserved for later use */ + H5T_STR_RESERVED_15 = 15 /**< reserved for later use */ } H5T_str_t; #define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined */ -/* Type of padding to use in other atomic types */ +/** + * Type of padding to use in other atomic types + */ +//! <!-- [H5T_pad_t_snip] --> typedef enum H5T_pad_t { - H5T_PAD_ERROR = -1, /*error */ - H5T_PAD_ZERO = 0, /*always set to zero */ - H5T_PAD_ONE = 1, /*always set to one */ - H5T_PAD_BACKGROUND = 2, /*set to background value */ + H5T_PAD_ERROR = -1, /**< error */ + H5T_PAD_ZERO = 0, /**< always set to zero */ + H5T_PAD_ONE = 1, /**< always set to one */ + H5T_PAD_BACKGROUND = 2, /**< set to background value */ - H5T_NPAD = 3 /*THIS MUST BE LAST */ + H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ } H5T_pad_t; +//! <!-- [H5T_pad_t_snip] --> -/* Commands sent to conversion functions */ +/** + * Commands sent to conversion functions + */ typedef enum H5T_cmd_t { - H5T_CONV_INIT = 0, /*query and/or initialize private data */ - H5T_CONV_CONV = 1, /*convert data from source to dest datatype */ - H5T_CONV_FREE = 2 /*function is being removed from path */ + H5T_CONV_INIT = 0, /**< query and/or initialize private data */ + H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */ + H5T_CONV_FREE = 2 /**< function is being removed from path */ } H5T_cmd_t; -/* How is the `bkg' buffer used by the conversion function? */ +/** + * How is the `bkg' buffer used by the conversion function? + */ typedef enum H5T_bkg_t { - H5T_BKG_NO = 0, /*background buffer is not needed, send NULL */ - H5T_BKG_TEMP = 1, /*bkg buffer used as temp storage only */ - H5T_BKG_YES = 2 /*init bkg buf with data before conversion */ + H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */ + H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */ + H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */ } H5T_bkg_t; -/* Type conversion client data */ +/** + * Type conversion client data + */ +//! <!-- [H5T_cdata_t_snip] --> typedef struct H5T_cdata_t { - H5T_cmd_t command; /*what should the conversion function do? */ - H5T_bkg_t need_bkg; /*is the background buffer needed? */ - hbool_t recalc; /*recalculate private data */ - void * priv; /*private data */ + H5T_cmd_t command; /**< what should the conversion function do? */ + H5T_bkg_t need_bkg; /**< is the background buffer needed? */ + hbool_t recalc; /**< recalculate private data */ + void * priv; /**< private data */ } H5T_cdata_t; +//! <!-- [H5T_cdata_t_snip] --> -/* Conversion function persistence */ +/** + * Conversion function persistence + */ typedef enum H5T_pers_t { - H5T_PERS_DONTCARE = -1, /*wild card */ - H5T_PERS_HARD = 0, /*hard conversion function */ - H5T_PERS_SOFT = 1 /*soft conversion function */ + H5T_PERS_DONTCARE = -1, /**< wild card */ + H5T_PERS_HARD = 0, /**< hard conversion function */ + H5T_PERS_SOFT = 1 /**< soft conversion function */ } H5T_pers_t; -/* The order to retrieve atomic native datatype */ +/** + * The order to retrieve atomic native datatype + */ +//! <!-- [H5T_direction_t_snip] --> typedef enum H5T_direction_t { - H5T_DIR_DEFAULT = 0, /*default direction is inscendent */ - H5T_DIR_ASCEND = 1, /*in inscendent order */ - H5T_DIR_DESCEND = 2 /*in descendent order */ + H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */ + H5T_DIR_ASCEND = 1, /**< in inscendent order */ + H5T_DIR_DESCEND = 2 /**< in descendent order */ } H5T_direction_t; +//! <!-- [H5T_direction_t_snip] --> -/* The exception type passed into the conversion callback function */ +/** + * The exception type passed into the conversion callback function + */ typedef enum H5T_conv_except_t { - H5T_CONV_EXCEPT_RANGE_HI = 0, /*source value is greater than destination's range */ - H5T_CONV_EXCEPT_RANGE_LOW = 1, /*source value is less than destination's range */ - H5T_CONV_EXCEPT_PRECISION = 2, /*source value loses precision in destination */ - H5T_CONV_EXCEPT_TRUNCATE = 3, /*source value is truncated in destination */ - H5T_CONV_EXCEPT_PINF = 4, /*source value is positive infinity(floating number) */ - H5T_CONV_EXCEPT_NINF = 5, /*source value is negative infinity(floating number) */ - H5T_CONV_EXCEPT_NAN = 6 /*source value is NaN(floating number) */ + H5T_CONV_EXCEPT_RANGE_HI = 0, + /**< Source value is greater than destination's range */ + H5T_CONV_EXCEPT_RANGE_LOW = 1, + /**< Source value is less than destination's range */ + H5T_CONV_EXCEPT_PRECISION = 2, + /**< Source value loses precision in destination */ + H5T_CONV_EXCEPT_TRUNCATE = 3, + /**< Source value is truncated in destination */ + H5T_CONV_EXCEPT_PINF = 4, + /**< Source value is positive infinity */ + H5T_CONV_EXCEPT_NINF = 5, + /**< Source value is negative infinity */ + H5T_CONV_EXCEPT_NAN = 6 + /**< Source value is \c NaN (not a number, including \c QNaN and \c SNaN) */ } H5T_conv_except_t; -/* The return value from conversion callback function H5T_conv_except_func_t */ +/** + * The return value from conversion callback function H5T_conv_except_func_t() + */ typedef enum H5T_conv_ret_t { - H5T_CONV_ABORT = -1, /*abort conversion */ - H5T_CONV_UNHANDLED = 0, /*callback function failed to handle the exception */ - H5T_CONV_HANDLED = 1 /*callback function handled the exception successfully */ + H5T_CONV_ABORT = -1, /**< abort conversion */ + H5T_CONV_UNHANDLED = 0, /**< callback function failed to handle the exception */ + H5T_CONV_HANDLED = 1 /**< callback function handled the exception successfully */ } H5T_conv_ret_t; -/* Variable Length Datatype struct in memory */ -/* (This is only used for VL sequences, not VL strings, which are stored in char *'s) */ +/** + * Variable Length Datatype struct in memory (This is only used for VL + * sequences, not VL strings, which are stored in char *'s) + */ typedef struct { - size_t len; /* Length of VL data (in base type units) */ - void * p; /* Pointer to VL data */ + size_t len; /**< Length of VL data (in base type units) */ + void * p; /**< Pointer to VL data */ } hvl_t; /* Variable Length String information */ -#define H5T_VARIABLE \ - ((size_t)( \ - -1)) /* Indicate that a string is variable length (null-terminated in C, instead of fixed length) */ +/** + * Indicate that a string is variable length (null-terminated in C, instead of + * fixed length) + */ +#define H5T_VARIABLE ((size_t)(-1)) /* Opaque information */ -#define H5T_OPAQUE_TAG_MAX 256 /* Maximum length of an opaque tag */ - /* This could be raised without too much difficulty */ +/** + * Maximum length of an opaque tag + * \internal This could be raised without too much difficulty + */ +#define H5T_OPAQUE_TAG_MAX 256 #ifdef __cplusplus extern "C" { #endif -/* All datatype conversion functions are... */ +/** + * All datatype conversion functions are... + */ +//! <!-- [H5T_conv_t_snip] --> typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist); +//! <!-- [H5T_conv_t_snip] --> -/* Exception handler. If an exception like overflow happenes during conversion, - * this function is called if it's registered through H5Pset_type_conv_cb. +//! <!-- [H5T_conv_except_func_t_snip] --> +/** + * \brief Exception handler. + * + * \param[in] except_type The kind of exception that occurred + * \param[in] src_id Source datatype identifier + * \param[in] dst_id Destination datatype identifier + * \param[in] src_buf Source data buffer + * \param[in,out] dst_buf Destination data buffer + * \param[in,out] user_data Callback context + * \returns Valid callback function return values are #H5T_CONV_ABORT, + * #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED. + * + * \details If an exception like overflow happenes during conversion, this + * function is called if it's registered through H5Pset_type_conv_cb(). + * */ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data); +//! <!-- [H5T_conv_except_func_t_snip] --> /* When this header is included from a private header, don't make calls to H5open() */ #undef H5OPEN -#ifndef _H5private_H +#ifndef H5private_H #define H5OPEN H5open(), -#else /* _H5private_H */ +#else /* H5private_H */ #define H5OPEN -#endif /* _H5private_H */ +#endif /* H5private_H */ /* * The IEEE floating point types in various byte orders. */ +/** + * \ingroup PDTIEEE + * 32-bit big-endian IEEE floating-point numbers + */ #define H5T_IEEE_F32BE (H5OPEN H5T_IEEE_F32BE_g) +/** + * \ingroup PDTIEEE + * 32-bit little-endian IEEE floating-point numbers + */ #define H5T_IEEE_F32LE (H5OPEN H5T_IEEE_F32LE_g) +/** + * \ingroup PDTIEEE + * 64-bit big-endian IEEE floating-point numbers + */ #define H5T_IEEE_F64BE (H5OPEN H5T_IEEE_F64BE_g) +/** + * \ingroup PDTIEEE + * 64-bit little-endian IEEE floating-point numbers + */ #define H5T_IEEE_F64LE (H5OPEN H5T_IEEE_F64LE_g) H5_DLLVAR hid_t H5T_IEEE_F32BE_g; H5_DLLVAR hid_t H5T_IEEE_F32LE_g; @@ -239,31 +327,135 @@ H5_DLLVAR hid_t H5T_IEEE_F64LE_g; * These are "standard" types. For instance, signed (2's complement) and * unsigned integers of various sizes and byte orders. */ -#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g) -#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g) -#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g) -#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g) -#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g) -#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g) -#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g) -#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g) -#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g) -#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g) -#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g) -#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g) -#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g) -#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g) -#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g) -#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g) -#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g) -#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g) -#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g) -#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g) -#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g) -#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g) -#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g) -#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g) -#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian signed integers + */ +#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian signed integers + */ +#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian signed integers + */ +#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian signed integers + */ +#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian signed integers + */ +#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian signed integers + */ +#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian signed integers + */ +#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian signed integers + */ +#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian unsigned integers + */ +#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian unsigned integers + */ +#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian unsigned integers + */ +#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian unsigned integers + */ +#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian unsigned integers + */ +#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian unsigned integers + */ +#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian unsigned integers + */ +#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian unsigned integers + */ +#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian bitfield + */ +#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian bitfield + */ +#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian bitfield + */ +#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian bitfield + */ +#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian bitfield + */ +#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian bitfield + */ +#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian bitfield + */ +#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian bitfield + */ +#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g) +/** + * \ingroup PDTSTD + * Object reference + */ +#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g) +/** + * \ingroup PDTSTD + * Dataset region reference + */ #define H5T_STD_REF_DSETREG (H5OPEN H5T_STD_REF_DSETREG_g) H5_DLLVAR hid_t H5T_STD_I8BE_g; H5_DLLVAR hid_t H5T_STD_I8LE_g; @@ -295,9 +487,21 @@ H5_DLLVAR hid_t H5T_STD_REF_DSETREG_g; /* * Types which are particular to Unix. */ +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D32BE (H5OPEN H5T_UNIX_D32BE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D32LE (H5OPEN H5T_UNIX_D32LE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D64BE (H5OPEN H5T_UNIX_D64BE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D64LE (H5OPEN H5T_UNIX_D64LE_g) H5_DLLVAR hid_t H5T_UNIX_D32BE_g; H5_DLLVAR hid_t H5T_UNIX_D32LE_g; @@ -308,12 +512,20 @@ H5_DLLVAR hid_t H5T_UNIX_D64LE_g; * Types particular to the C language. String types use `bytes' instead * of `bits' as their size. */ +/** + * \ingroup PDTS + * String datatype in C (size defined in bytes rather than in bits) + */ #define H5T_C_S1 (H5OPEN H5T_C_S1_g) H5_DLLVAR hid_t H5T_C_S1_g; /* * Types particular to Fortran. */ +/** + * \ingroup PDTS + * String datatype in Fortran (as defined for the HDF5 C library) + */ #define H5T_FORTRAN_S1 (H5OPEN H5T_FORTRAN_S1_g) H5_DLLVAR hid_t H5T_FORTRAN_S1_g; @@ -321,63 +533,239 @@ H5_DLLVAR hid_t H5T_FORTRAN_S1_g; * These types are for Intel CPU's. They are little endian with IEEE * floating point. */ -#define H5T_INTEL_I8 H5T_STD_I8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian signed (2's complement) integers for Intel CPUs + */ +#define H5T_INTEL_I8 H5T_STD_I8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I16 H5T_STD_I16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I32 H5T_STD_I32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I64 H5T_STD_I64LE -#define H5T_INTEL_U8 H5T_STD_U8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian unsigned integers for Intel CPUs + */ +#define H5T_INTEL_U8 H5T_STD_U8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U16 H5T_STD_U16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U32 H5T_STD_U32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U64 H5T_STD_U64LE -#define H5T_INTEL_B8 H5T_STD_B8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian bitfield for Intel CPUs + */ +#define H5T_INTEL_B8 H5T_STD_B8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B16 H5T_STD_B16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B32 H5T_STD_B32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B64 H5T_STD_B64LE +/** + * \ingroup PDTX86 + * 32-bit little-endian IEEE floating-point numbers for Intel CPUs + */ #define H5T_INTEL_F32 H5T_IEEE_F32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian IEEE floating-point numbers for Intel CPUs + */ #define H5T_INTEL_F64 H5T_IEEE_F64LE /* * These types are for DEC Alpha CPU's. They are little endian with IEEE * floating point. */ -#define H5T_ALPHA_I8 H5T_STD_I8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ +#define H5T_ALPHA_I8 H5T_STD_I8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I16 H5T_STD_I16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I32 H5T_STD_I32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I64 H5T_STD_I64LE -#define H5T_ALPHA_U8 H5T_STD_U8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian unsigned integers for DEC Alpha CPUs + */ +#define H5T_ALPHA_U8 H5T_STD_U8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U16 H5T_STD_U16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U32 H5T_STD_U32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U64 H5T_STD_U64LE -#define H5T_ALPHA_B8 H5T_STD_B8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian bitfield for DEC Alpha CPUs + */ +#define H5T_ALPHA_B8 H5T_STD_B8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B16 H5T_STD_B16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B32 H5T_STD_B32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B64 H5T_STD_B64LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs + */ #define H5T_ALPHA_F32 H5T_IEEE_F32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs + */ #define H5T_ALPHA_F64 H5T_IEEE_F64LE /* * These types are for MIPS cpu's commonly used in SGI systems. They are big * endian with IEEE floating point. */ -#define H5T_MIPS_I8 H5T_STD_I8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ +#define H5T_MIPS_I8 H5T_STD_I8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I16 H5T_STD_I16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I32 H5T_STD_I32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I64 H5T_STD_I64BE -#define H5T_MIPS_U8 H5T_STD_U8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian unsigned integers for SGI MIPS CPUs + */ +#define H5T_MIPS_U8 H5T_STD_U8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U16 H5T_STD_U16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U32 H5T_STD_U32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U64 H5T_STD_U64BE -#define H5T_MIPS_B8 H5T_STD_B8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian bitfield for SGI MIPS CPUs + */ +#define H5T_MIPS_B8 H5T_STD_B8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B16 H5T_STD_B16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B32 H5T_STD_B32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B64 H5T_STD_B64BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian IEEE floating-point numbers for MIPS CPUs + */ #define H5T_MIPS_F32 H5T_IEEE_F32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian IEEE floating-point numbers for MIPS CPUs + */ #define H5T_MIPS_F64 H5T_IEEE_F64BE /* * The VAX floating point types (i.e. in VAX byte order) */ +/** + * \ingroup PDTALPHA + * 32-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs + */ #define H5T_VAX_F32 (H5OPEN H5T_VAX_F32_g) +/** + * \ingroup PDTALPHA + * 64-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs + */ #define H5T_VAX_F64 (H5OPEN H5T_VAX_F64_g) H5_DLLVAR hid_t H5T_VAX_F32_g; H5_DLLVAR hid_t H5T_VAX_F64_g; @@ -391,32 +779,128 @@ H5_DLLVAR hid_t H5T_VAX_F64_g; * to C's `long long' and LDOUBLE is `long double' (these types might be the * same as `LONG' and `DOUBLE' respectively). */ -#define H5T_NATIVE_CHAR (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR) -#define H5T_NATIVE_SCHAR (H5OPEN H5T_NATIVE_SCHAR_g) -#define H5T_NATIVE_UCHAR (H5OPEN H5T_NATIVE_UCHAR_g) -#define H5T_NATIVE_SHORT (H5OPEN H5T_NATIVE_SHORT_g) +/** + * \ingroup PDTNAT + * C-style \c char + */ +#define H5T_NATIVE_CHAR (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR) +/** + * \ingroup PDTNAT + * C-style \Code{signed char} + */ +#define H5T_NATIVE_SCHAR (H5OPEN H5T_NATIVE_SCHAR_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned char} + */ +#define H5T_NATIVE_UCHAR (H5OPEN H5T_NATIVE_UCHAR_g) +/** + * \ingroup PDTNAT + * C-style \Code{short} + */ +#define H5T_NATIVE_SHORT (H5OPEN H5T_NATIVE_SHORT_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned short} + */ #define H5T_NATIVE_USHORT (H5OPEN H5T_NATIVE_USHORT_g) -#define H5T_NATIVE_INT (H5OPEN H5T_NATIVE_INT_g) -#define H5T_NATIVE_UINT (H5OPEN H5T_NATIVE_UINT_g) -#define H5T_NATIVE_LONG (H5OPEN H5T_NATIVE_LONG_g) -#define H5T_NATIVE_ULONG (H5OPEN H5T_NATIVE_ULONG_g) -#define H5T_NATIVE_LLONG (H5OPEN H5T_NATIVE_LLONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{int} + */ +#define H5T_NATIVE_INT (H5OPEN H5T_NATIVE_INT_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned int} + */ +#define H5T_NATIVE_UINT (H5OPEN H5T_NATIVE_UINT_g) +/** + * \ingroup PDTNAT + * C-style \Code{long} + */ +#define H5T_NATIVE_LONG (H5OPEN H5T_NATIVE_LONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned long} + */ +#define H5T_NATIVE_ULONG (H5OPEN H5T_NATIVE_ULONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{long long} + */ +#define H5T_NATIVE_LLONG (H5OPEN H5T_NATIVE_LLONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned long long} + */ #define H5T_NATIVE_ULLONG (H5OPEN H5T_NATIVE_ULLONG_g) -#define H5T_NATIVE_FLOAT (H5OPEN H5T_NATIVE_FLOAT_g) +/** + * \ingroup PDTNAT + * C-style \Code{float} + */ +#define H5T_NATIVE_FLOAT (H5OPEN H5T_NATIVE_FLOAT_g) +/** + * \ingroup PDTNAT + * C-style \Code{double} + */ #define H5T_NATIVE_DOUBLE (H5OPEN H5T_NATIVE_DOUBLE_g) #if H5_SIZEOF_LONG_DOUBLE != 0 +/** + * \ingroup PDTNAT + * C-style \Code{long double} + */ #define H5T_NATIVE_LDOUBLE (H5OPEN H5T_NATIVE_LDOUBLE_g) #endif -#define H5T_NATIVE_B8 (H5OPEN H5T_NATIVE_B8_g) -#define H5T_NATIVE_B16 (H5OPEN H5T_NATIVE_B16_g) -#define H5T_NATIVE_B32 (H5OPEN H5T_NATIVE_B32_g) -#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g) +/** + * \ingroup PDTNAT + * HDF5 8-bit bitfield based on native types + */ +#define H5T_NATIVE_B8 (H5OPEN H5T_NATIVE_B8_g) +/** + * \ingroup PDTNAT + * HDF5 16-bit bitfield based on native types + */ +#define H5T_NATIVE_B16 (H5OPEN H5T_NATIVE_B16_g) +/** + * \ingroup PDTNAT + * HDF5 32-bit bitfield based on native types + */ +#define H5T_NATIVE_B32 (H5OPEN H5T_NATIVE_B32_g) +/** + * \ingroup PDTNAT + * HDF5 64-bit bitfield based on native types + */ +#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g) +/** + * \ingroup PDTNAT + * HDF5 opaque unit based on native types + */ #define H5T_NATIVE_OPAQUE (H5OPEN H5T_NATIVE_OPAQUE_g) -#define H5T_NATIVE_HADDR (H5OPEN H5T_NATIVE_HADDR_g) -#define H5T_NATIVE_HSIZE (H5OPEN H5T_NATIVE_HSIZE_g) +/** + * \ingroup PDTNAT + * HDF5 address type based on native types + */ +#define H5T_NATIVE_HADDR (H5OPEN H5T_NATIVE_HADDR_g) +/** + * \ingroup PDTNAT + * HDF5 size type based on native types + */ +#define H5T_NATIVE_HSIZE (H5OPEN H5T_NATIVE_HSIZE_g) +/** + * \ingroup PDTNAT + * HDF5 signed size type based on native types + */ #define H5T_NATIVE_HSSIZE (H5OPEN H5T_NATIVE_HSSIZE_g) -#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g) -#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g) +/** + * \ingroup PDTNAT + * HDF5 error code type based on native types + */ +#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g) +/** + * \ingroup PDTNAT + * HDF5 Boolean type based on native types + */ +#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g) H5_DLLVAR hid_t H5T_NATIVE_SCHAR_g; H5_DLLVAR hid_t H5T_NATIVE_UCHAR_g; H5_DLLVAR hid_t H5T_NATIVE_SHORT_g; @@ -444,12 +928,30 @@ H5_DLLVAR hid_t H5T_NATIVE_HERR_g; H5_DLLVAR hid_t H5T_NATIVE_HBOOL_g; /* C9x integer types */ -#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g) -#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g) -#define H5T_NATIVE_INT_LEAST8 (H5OPEN H5T_NATIVE_INT_LEAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST8 (H5OPEN H5T_NATIVE_INT_LEAST8_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST8 (H5OPEN H5T_NATIVE_UINT_LEAST8_g) -#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g) -#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g) H5_DLLVAR hid_t H5T_NATIVE_INT8_g; H5_DLLVAR hid_t H5T_NATIVE_UINT8_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST8_g; @@ -457,12 +959,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST8_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST8_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST8_g; -#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g) -#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g) -#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST16 (H5OPEN H5T_NATIVE_UINT_LEAST16_g) -#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g) -#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g) H5_DLLVAR hid_t H5T_NATIVE_INT16_g; H5_DLLVAR hid_t H5T_NATIVE_UINT16_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST16_g; @@ -470,12 +990,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST16_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST16_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST16_g; -#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g) -#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g) -#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST32 (H5OPEN H5T_NATIVE_UINT_LEAST32_g) -#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g) -#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g) H5_DLLVAR hid_t H5T_NATIVE_INT32_g; H5_DLLVAR hid_t H5T_NATIVE_UINT32_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST32_g; @@ -483,12 +1021,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST32_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST32_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST32_g; -#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g) -#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g) -#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST64 (H5OPEN H5T_NATIVE_UINT_LEAST64_g) -#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g) -#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g) H5_DLLVAR hid_t H5T_NATIVE_INT64_g; H5_DLLVAR hid_t H5T_NATIVE_UINT64_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST64_g; @@ -497,95 +1053,1743 @@ H5_DLLVAR hid_t H5T_NATIVE_INT_FAST64_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; /* Operations defined on all datatypes */ -H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); -H5_DLL hid_t H5Tcopy(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Creates a new datatype. + * + * \param[in] type Class of datatype to create + * \param[in] size Size, in bytes, of the datatype being created + * + * \return \hid_t{datatype} + * + * \details H5Tcreate() creates a new datatype of the specified class with the + * specified number of bytes. This function is used only with the + * following datatype classes: + * - #H5T_COMPOUND + * - #H5T_OPAQUE + * - #H5T_ENUM + * - #H5T_STRING + * + * Other datatypes, including integer and floating-point datatypes, + * are typically created by using H5Tcopy() to copy and modify a + * predefined datatype. + * + * When creating a variable-length string datatype, \p size must + * be #H5T_VARIABLE; see \ref_vlen_strings. + * + * When creating a fixed-length string datatype, \p size will + * be the length of the string in bytes. The length of the + * string in characters will depend on i the encoding used; see + * H5Pset_char_encoding(). + * + * ENUMs created with this function have a signed native integer + * base datatype. Use H5Tenum_create() if a different integer base + * datatype is required. + * + * The datatype identifier returned from this function should be + * released with H5Tclose or resource leaks will result. + * + * \see H5Tclose() + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); +/** + * \ingroup H5T + * + * \brief Copies an existing datatype. + * + * \type_id + * + * \return \hid_t{datatype} + * + * \details H5Tcopy() makes a copy of an existing datatype. The returned type + * is always transient and unlocked. + * + * The \p type_id argument can be either a datatype identifier, + * a predefined datatype (defined in H5Tpublic.h), or a dataset + * identifier. If \p type_id is a dataset identifier, this function + * returns a transient, modifiable datatype which is a copy of the + * dataset's datatype. + * + * The returned datatype identifier should be released with H5Tclose() + * to prevent resource leak. + * + */ +H5_DLL hid_t H5Tcopy(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Releases a datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tclose() releases the datatype \p dtype_id. Further access + * through this datatype identifier is illegal. Failure to release + * a datatype with this call will result in resource leaks. + * + */ H5_DLL herr_t H5Tclose(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether two datatype identifiers refer to the same datatype + * + * \type_id{type1_id} + * \type_id{type2_id} + * + * \return \htri_t + * + * \details H5Tequal() determines whether two datatype identifiers refer to + * the same datatype. + * + * \since 1.6 or earlier + * + */ H5_DLL htri_t H5Tequal(hid_t type1_id, hid_t type2_id); +/** + * \ingroup H5T + * + * \brief Locks a datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tlock() locks the datatype specified by the dtype_id identifier, + * making it read-only and non-destructible. This is normally done by + * the library for predefined datatypes so the application does not + * inadvertently change or delete a predefined type. Once a datatype + * is locked it can never be unlocked. + * + */ H5_DLL herr_t H5Tlock(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Commits a transient datatype, linking it into the file and creating + * a new committed datatype + * + * \fg_loc_id + * \param[in] name Name given to committed datatype + * \type_id Identifier of datatype to be committed and, upon function’s + * return, identifier for the committed datatype + * \lcpl_id + * \tcpl_id + * \tapl_id + * + * \return \herr_t + * + * \details H5Tcommit2() saves a transient datatype as an immutable committed + * datatype in a file. The datatype specified by \p dtype_id is + * committed to the file with the name name at the location specified + * by \p loc_id and with the datatype creation and access property + * lists \p tcpl_id and \p tapl_id, respectively. + * + * \p loc_id may be a file identifier, or a group identifier within + * that file. \p name may be either an absolute path in the file or + * a relative path from \p loc_id naming the newly-commited datatype. + * + * The link creation property list, \p lcpl_id, governs creation of + * the link(s) by which the new committed datatype is accessed and + * the creation of any intermediate groups that may be missing. + * + * Once commited, this datatype may be used to define the datatype + * of any other dataset or attribute in the file. + * + * This function will not accept a datatype that cannot actually hold + * information. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * Committed datatypes are sometimes referred to as named datatypes. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accomodate actual data, such as a compound datatype + * with no fields or an enumerated datatype with no members. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id); -H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5T + * + * \brief Opens a committed (named) datatype + * + * \fgdta_loc_id + * \param[in] name Name of the datatype to open + * \tapl_id + * + * \return \hid_t{datatype} + * + * \details H5Topen2() opens a committed datatype at the location specified + * by \p loc_id and returns an identifier for the datatype. \p + * loc_id is either a file or group identifier. The identifier should + * eventually be closed by calling H5Tclose() to release resources. + * + * The committed datatype is opened with the datatype access property + * list tapl_id. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); +/** + * \ingroup H5T + * + * \brief Commits a transient datatype to a file, creating a new named + * datatype, but does not link it into the file structure + * + * \fg_loc_id + * \type_id + * \tcpl_id + * \tapl_id + * + * \return \herr_t + * + * \details H5Tcommit_anon() commits a transient datatype (not immutable) + * to a file, turning it into a named datatype with the specified + * creation and property lists. With default property lists, + * #H5P_DEFAULT, H5Tcommit_anon() provides similar functionality to + * that of H5Tcommit(), with the differences described below. + * + * #H5P_DEFAULT can be passed in for the datatype creation property + * list identifier, \p tcpl_id. The datatype access property list + * identifier, \p tapl_id, is provided for future functionality and + * is not used at this time. This parameter should always be passed + * as the value #H5P_DEFAULT. + * + * Note that H5Tcommit_anon() does not link this newly-committed + * datatype into the file. After the H5Tcommit_anon() call, the + * datatype identifier \p type_id must be linked into the HDF5 file + * structure with H5Olink() or it will be deleted from the file when + * the file is closed. + * + * The differences between this function and H5Tcommit() are as follows: + * \li H5Tcommit_anon() explicitly includes property lists, + * which provides for greater control of the creation process + * and of the properties of the new named datatype. H5Tcommit() + * always uses default properties. + * \li H5Tcommit_anon() neither provides the new named datatype’s + * name nor links it into the HDF5 file structure; those actions + * must be performed separately through a call to H5Olink(), + * which offers greater control over linking. + * + * This function will not accept a datatype that cannot actually + * hold data. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accomodate actual data, such as a compound datatype + * with no fields or an enumerated datatype with no members. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tcommit_anon(hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id); -H5_DLL hid_t H5Tget_create_plist(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Returns a copy of a datatype's creation property list + * + * \type_id + * + * \return \hid_t{datatype creation property list} + * + * \details H5Tget_create_plist() returns a property list identifier + * for the datatype creation property list associated with the datatype + * specified by \p type_id. + * + * The creation property list identifier should be released with + * H5Pclose() to prevent memory leaks. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Tget_create_plist(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether a datatype is a committed type or a transient type + * + * \type_id + * + * \return \htri_t + * + * \details H5Tcommitted() queries a type to determine whether the type + * specified by the \p dtype_id identifier is a committed (formerly + * known as a \Emph{named}) type or a transient type. If this function returns + * a positive value, then the type is committed (that is, it has been + * committed, perhaps by some other application). Datasets which + * return committed datatypes with H5Dget_type() are able to share + * the datatype with other datasets in the same file. + * + * \version 1.8.0 Fortran API was added + * + * \since 1.6 or earlier + * + */ H5_DLL htri_t H5Tcommitted(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Encodes a datatype object description into a binary buffer + * + * \param[in] obj_id Identifier of the object to be encoded + * \param[in,out] buf Buffer for the object to be encoded into. + * \param[in,out] nalloc IN: The size of the allocated buffer + * OUT: The size of the buffer needed + * + * \return \herr_t + * + * \details H5Tencode() Given datatype identifier, H5Tencode() converts a + * datatype description into binary form in a buffer. Using this + * binary form in the buffer, a datatype object can be reconstructed + * using H5Tdecode() to return a new object handle (\ref hid_t) for + * this datatype. + * + * If the provided buffer is NULL, only the size of buffer needed is + * returned through \p nalloc. + * + * A preliminary H5Tencode() call can be made to find out the size + * of the buffer needed. This value is returned as \p nalloc. That + * value can then be assigned to \p nalloc for a second H5Tencode() + * call, which will retrieve the actual encoded object. + * + * If the library finds that \p nalloc is not big enough for the + * object, it simply returns the size of the buffer needed through + * \p nalloc without encoding the provided buffer. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc); -H5_DLL hid_t H5Tdecode(const void *buf); +/** + * \ingroup H5T + * + * \brief Decodes a binary object description of datatype and return a new + * object handle + * + * \param[in] buf Buffer for the datatype object to be decoded + * + * \return \hid_t{datatype} + * + * \details H5Tdecode() Given an object description of datatype in binary in a + * buffer, H5Tdecode() reconstructs the HDF5 datatype object and + * returns a new object handle for it. The binary description of + * the object is encoded by H5Tencode(). User is responsible for + * passing in the right buffer. + * + * The datatype identifier returned by this function can be released + * with H5Tclose() when the identifier is no longer needed so that + * resource leaks will not develop. + * + */ +H5_DLL hid_t H5Tdecode(const void *buf); /* Operations defined on compound datatypes */ +/** + * \ingroup COMPOUND + * + * \brief Adds a new member to a compound datatype. + * + * \type_id{parent_id} + * \param[in] name Name of the field to insert + * \param[in] offset Offset in memory structure of the field to insert + * \param[in] member_id Datatype identifier of the field to insert + * + * \return \herr_t + * + * \details H5Tinsert() adds another member to the compound datatype, specified + * \p type_id. + * + * The new member has a \p name which must be unique within the + * compound datatype. The \p offset argument defines the start of the + * member in an instance of the compound datatype, and \p member_id + * is the datatype identifier of the new member. + * + * \note Members of a compound datatype do not have to be atomic + * datatypes; a compound datatype can have a member which is a + * compound datatype. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id); +/** + * \ingroup COMPOUND + * + * \brief Recursively removes padding from within a compound datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tpack() recursively removes padding from within a compound + * datatype to make it more efficient (space-wise) to store that data. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tpack(hid_t type_id); /* Operations defined on enumeration datatypes */ -H5_DLL hid_t H5Tenum_create(hid_t base_id); +/** + * \ingroup ENUM + * + * \brief Creates a new enumeration datatype + * + * \param[in] base_id Datatype identifier for the base datatype. Must be an + * integer datatype + * + * \return \hid_t{enumeration datatype} + * + * \details H5Tenum_create() creates a new enumeration datatype based on the + * specified base datatype, dtype_id, which must be an integer datatype. + * + * If a particular architecture datatype is required, a little endian + * or big endian datatype for example, use a native datatype as the + * base datatype and use H5Tconvert() on values as they are read + * from or written to a dataset. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Tenum_create(hid_t base_id); +/** + * \ingroup ENUM + * + * \brief Inserts a new enumeration datatype member + * + * \type_id{type} + * \param[in] name Name of the new member + * \param[in] value Pointer to the value of the new member + * + * \return \herr_t + * + * \details H5Tenum_insert() inserts a new enumeration datatype member into an + * enumeration datatype. + * + * \p type_id is the datatype identifier for the enumeration datatype, + * \p name is the name of the new member, and \p value points to the + * value of the new member. + * + * \p name and \p value must both be unique within \p dtype_id. + * + * \p value points to data which must be of the integer base datatype + * used when the enumeration datatype was created. If a particular + * architecture datatype is required, a little endian or big endian + * datatype for example, use a native datatype as the base datatype + * and use H5Tconvert() on values as they are read from or written + * to a dataset. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_insert(hid_t type, const char *name, const void *value); +/** + * \ingroup ENUM + * + * \brief Returns the symbol name corresponding to a specified member of an + * enumeration datatype + * + * \type_id{type} + * \param[in] value Value of the enumeration datatype + * \param[out] name Buffer for output of the symbol name + * \param[in] size Anticipated size of the symbol name, in bytes + * + * \return Returns a non-negative value if successful. Otherwise returns a + * negative value + * + * \details H5Tenum_nameof() finds the symbol name that corresponds to the + * specified \p value of the enumeration datatype \p type. + * + * At most \p size characters of the symbol \p name are copied into + * the \p name buffer. If the entire symbol name and null terminator + * do not fit in the name buffer, then as many characters as possible + * are copied (not null terminated) and the function fails. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_nameof(hid_t type, const void *value, char *name /*out*/, size_t size); +/** + * \ingroup ENUM + * + * \brief Returns the value corresponding to a specified member of an + * enumeration datatype + * + * \type_id{type} + * \param[in] name Symbol name of the enumeration datatype + * \param[out] value Buffer for the value of the enumeration datatype + * + * \return \herr_t + * + * \details H5Tenum_valueof() finds the value that corresponds to the + * specified name of the enumeration datatype \p dtype_id. + * + * Values returned in \p value will be of the enumerated type’s + * base type, that is, the datatype used by H5Tenum_create() when + * the enumerated type was created. + * + * The \p value buffer must be at least large enough to hold a value + * of that base type. If the size is unknown, you can determine it + * with H5Tget_size(). + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/); /* Operations defined on variable-length datatypes */ +/** + * \ingroup VLEN + * + * \brief Creates a new variable-length array datatype + * + * \type_id{base_id}, the element type of the datatype to create + * + * \return \hid_t{variable-length datatype} + * + * \details H5Tvlen_create() creates a new one-dimensional array datatype of + * variable-length (VL) with the base datatype \p base_id. + * + * This one-dimensional array often represents a data sequence of the + * base datatype, such as characters for character sequences or vertex + * coordinates for polygon lists. The base type specified for the VL + * datatype can be any HDF5 datatype, including another VL datatype, a + * compound datatype, or an atomic datatype. + * + * When necessary, use H5Tget_super() to determine the base type of + * the VL datatype. + * + * The datatype identifier returned from this function should be + * released with H5Tclose() or resource leaks will result. Under + * certain circumstances, H5Dvlen_reclaim() must also be used. + * + * \attention H5Tvlen_create() cannot be used to create a variable-length + * string datatype. H5Tvlen_create() called with a string or + * character base type creates a variable-length sequence of strings + * (a variable-length, 1-dimensional array), with each element of + * the array being of the string or character base type.\n + * To create a variable-length string datatype, see \ref_vlen_strings. + * + */ H5_DLL hid_t H5Tvlen_create(hid_t base_id); /* Operations defined on array datatypes */ +/** + * \ingroup ARRAY + * + * \brief Creates an array datatype object + * + * \param[in] base_id Datatype identifier for the array base datatype + * \param[in] ndims Rank of the array + * \param[in] dim Size of each array dimension + * + * \return \hid_t{array datatype} + * + * \details H5Tarray_create2() creates a new array datatype object.\n\n + * \p base_id is the datatype of every element of the array, i.e., + * of the number at each position in the array. + * + * \p ndims is the number of dimensions and the size of each dimension + * is specified in the array \p dim. The value of \p rank is + * currently limited to #H5S_MAX_RANK and must be greater than 0 + * (zero). All dimension sizes specified in \p dim must be greater + * than 0 (zero). + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Tarray_create2(hid_t base_id, unsigned ndims, const hsize_t dim[/* ndims */]); -H5_DLL int H5Tget_array_ndims(hid_t type_id); -H5_DLL int H5Tget_array_dims2(hid_t type_id, hsize_t dims[]); +/** + * \ingroup ARRAY + * + * \brief Returns the rank of an array datatype + * + * \type_id + * + * \return Returns the rank of the array if successful; otherwise returns a + * negative value. + * + * \details H5Tget_array_ndims() returns the rank, i.e., the number of + * dimensions, of an array datatype object. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_ndims(hid_t type_id); +/** + * \ingroup ARRAY + * + * \brief Retrieves sizes of array dimensions + * + * \type_id + * \param[out] dims Sizes of array dimensions + * + * \return Returns the non-negative number of dimensions of the array type + * if successful; otherwise returns a negative value. + * + * \details H5Tget_array_dims2() returns the sizes of the dimensions of the + * specified array datatype object in the array \p dims. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_dims2(hid_t type_id, hsize_t dims[]); /* Operations defined on opaque datatypes */ +/** + * \ingroup OPAQUE + * + * \brief Tags an opaque datatype + * + * \type_id{type} of an opaque datatype + * \param[in] tag Descriptive ASCII string with which the opaque datatype is + * to be tagged + * + * \return \herr_t + * + * \details H5Tset_tag() tags an opaque datatype \p type with a descriptive + * ASCII identifier, \p tag. + * + * \p tag is intended to provide a concise description; the maximum + * size is hard-coded in the HDF5 library as 256 bytes + * (#H5T_OPAQUE_TAG_MAX). + * + * \version 1.6.5 The #H5T_OPAQUE_TAG_MAX macro constant, specifying the + * maximum size of an opaque datatype tag, was added in + * H5Tpublic.h. + * + */ H5_DLL herr_t H5Tset_tag(hid_t type, const char *tag); -H5_DLL char * H5Tget_tag(hid_t type); +/** + * \ingroup OPAQUE + * + * \brief Gets the tag associated with an opaque datatype + * + * \type_id{type} of an opaque datatype + * + * \return Returns a pointer to an allocated string if successful; otherwise + * returns NULL. + * + * \details H5Tget_tag() returns the tag associated with the opaque datatype + * \p type. + * + * \attention The tag is returned via a pointer to an allocated string, which + * the caller must free. + * + */ +H5_DLL char *H5Tget_tag(hid_t type); /* Querying property values */ -H5_DLL hid_t H5Tget_super(hid_t type); +/** + * \ingroup H5T + * + * \brief Returns the base datatype from which a datatype is derived + * + * \type_id{type} + * + * \return \hid_t{datatype} + * + * \details H5Tget_super() returns the base datatype from which the datatype + * \p type_id is derived. In the case of an enumeration type, the + * return value is an integer type. + * + * The datatype identifier returned by this function must be released + * with H5Tclose() when the identifier is no longer needed so that + * resource leaks will not develop. + * + */ +H5_DLL hid_t H5Tget_super(hid_t type); +/** + * \ingroup H5T + * + * \brief Returns a datatype class + * + * \type_id + * + * \return Returns the datatype class if successful; otherwise #H5T_NO_CLASS. + * + * \details H5Tget_class() returns the class of the datatype \p type_id. + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \note The library returns #H5T_STRING for both fixed-length and + * variable-length strings. + * + * \note Unsupported datatype: The time datatype class, #H5T_TIME, + * is not supported. If #H5T_TIME is used, the resulting data will + * be readable and modifiable only on the originating computing + * platform; it will not be portable to other platforms. + * + */ H5_DLL H5T_class_t H5Tget_class(hid_t type_id); -H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); -H5_DLL size_t H5Tget_size(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether a datatype contains any datatypes of the given + * datatype class + * + * \type_id + * \param[in] cls Datatype class + * + * \return \htri_t + * + * \details H5Tdetect_class() determines whether the datatype specified in + * \p type_id contains any datatypes of the datatype class specified + * in \p dtype_class. + * + * This function is useful primarily in recursively examining all the + * fields and/or base types of compound, array, and variable-length + * datatypes. + * + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \since 1.6.0 + * + */ +H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); +/** + * \ingroup H5T + * + * \brief Returns the size of a datatype + * + * \type_id + * + * \return Returns the size of the datatype in bytes if successful; otherwise, + * returns 0. + * + * \details H5Tget_size() returns the size of a datatype in bytes. + * \li For atomic datatypes, array datatypes, compound datatypes, and + * other datatypes of a constant size, the returned value is the + * size of the actual datatype in bytes. + * \li For variable-length string datatypes the returned value is + * the size of the pointer to the actual string, or \c sizeof(\c + * char \c *). This function does not return the size of actual + * variable-length string data. + * \li For variable-length sequence datatypes (see H5Tvlen_create()), + * the returned value is the size of the \p hvl_t struct, or \c + * sizeof(\p hvl_t). The \p hvl_t struct contains a pointer to the + * actual data and a size value. This function does not return the + * size of actual variable-length sequence data. + * + * \see H5Tset_size() + * + * \since 1.2.0 + */ +H5_DLL size_t H5Tget_size(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Returns the byte order of an atomic datatype + * + * \type_id + * + * \return Returns a byte order constant if successful; otherwise returns + * #H5T_ORDER_ERROR (-1) + * + * \details H5Tget_order() returns the byte order of an atomic datatype. + * Possible return values are: + * \snippet this H5T_order_t_snip + * Members of a compound datatype need not have the same byte + * order. If members of a compound datatype have more than one of + * little endian, big endian, or VAX byte order, H5Tget_order() will + * return #H5T_ORDER_MIXED for the compound datatype. A byte order of + * #H5T_ORDER_NONE will, however, be ignored; for example, if one or + * more members of a compound datatype have byte order #H5T_ORDER_NONE + * but all other members have byte order #H5T_ORDER_LE, H5Tget_order() + * will return #H5T_ORDER_LE for the compound datatype. + * + * \since 1.2.0 + * + */ H5_DLL H5T_order_t H5Tget_order(hid_t type_id); -H5_DLL size_t H5Tget_precision(hid_t type_id); -H5_DLL int H5Tget_offset(hid_t type_id); -H5_DLL herr_t H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/); -H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Returns the precision of an atomic datatype + * + * \type_id + * + * \return Returns the number of significant bits if successful; otherwise 0 + * + * \details H5Tget_precision() returns the precision of an atomic datatype + * (for example, integer or float) or a datatype whose base (parent) + * type is an atomic type (for example, array, enum and variable + * length). The precision is the number of significant bits which, + * unless padding is present, is 8 times larger than the value + * returned by H5Tget_size(). + * + * \since 1.2.0 + * + */ +H5_DLL size_t H5Tget_precision(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the bit offset of the first significant bit + * + * \type_id + * + * \return Returns an offset value if successful; otherwise returns a + * negative value. + * + * \details H5Tget_offset() retrieves the bit offset of the first significant + * bit. The significant bits of an atomic datum can be offset from the + * beginning of the memory for that datum by an amount of padding. The + * 'offset' property specifies the number of bits of padding that + * appear to the "right of" the value. That is, if we have a 32-bit + * datum with 16-bits of precision having the value 0x1122 then it + * will be laid out in memory as (from small byte address toward + * larger byte addresses): + * \code{.unparsed} + * 0: [ pad] [0x11] [0x22] [ pad] + * 1: [ pad] [0x22] [0x11] [ pad] + * 2: [0x11] [ pad] [ pad] [0x22] + * 3: [0x22] [ pad] [ pad] [0x11] + * \endcode + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_offset(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the padding type of the least and most-significant bit padding + * + * \type_id + * \param[out] lsb Buffer for the least-significant bit padding type + * \param[out] msb Buffer for the most-significant bit padding type + * + * \return \herr_t + * + * \details H5Tget_pad() retrieves the padding type of the least and + * most-significant bit padding. Valid padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the sign type for an integer type + * + * \type_id + * + * \return Returns a valid sign type if successful; otherwise #H5T_SGN_ERROR (-1) + * + * \details H5Tget_sign() retrieves the sign type for an integer type. + * Valid types are: + * \snippet this H5T_sign_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves floating point datatype bit field information + * + * \type_id + * \param[out] spos Pointer to location to return floating-point sign bit + * \param[out] epos Pointer to location to return exponent bit-position + * \param[out] esize Pointer to location to return size of exponent in bits + * \param[out] mpos Pointer to location to return mantissa bit-position + * \param[out] msize Pointer to location to return size of mantissa in bits + * + * \return \herr_t + * + * \details H5Tget_fields() retrieves information about the locations of + * the various bit fields of a floating point datatype. The field + * positions are bit positions in the significant region of the + * datatype. Bits are numbered with the least significant bit number + * zero. Any (or even all) of the arguments can be null pointers. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tget_fields(hid_t type_id, size_t *spos /*out*/, size_t *epos /*out*/, size_t *esize /*out*/, size_t *mpos /*out*/, size_t *msize /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the exponent bias of a floating-point type + * + * \type_id + * + * \return Returns the bias if successful and 0, otherwise. + * + * \details H5Tget_ebias() retrieves the exponent bias of a floating-point type. + * + * \since 1.2.0 + * + */ H5_DLL size_t H5Tget_ebias(hid_t type_id); -H5_DLL H5T_norm_t H5Tget_norm(hid_t type_id); -H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); -H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); -H5_DLL int H5Tget_nmembers(hid_t type_id); -H5_DLL char * H5Tget_member_name(hid_t type_id, unsigned membno); -H5_DLL int H5Tget_member_index(hid_t type_id, const char *name); -H5_DLL size_t H5Tget_member_offset(hid_t type_id, unsigned membno); +/** + * -------------------------------------------------------------------------- + * \ingroup ATOM + * + * \brief Retrieves mantissa normalization of a floating-point datatype + * + * \type_id + * + * \return Returns a valid normalization type if successful; otherwise + * returns #H5T_NORM_ERROR (-1) + * + * \details H5Tget_norm() retrieves the mantissa normalization of a + * floating-point datatype. Valid normalization types are: + * \snippet this H5T_norm_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_norm_t H5Tget_norm(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the internal padding type for unused bits in floating-point + * datatypes + * + * \type_id + * + * \return Returns a valid padding type if successful; otherwise returns + * #H5T_PAD_ERROR (-1). + * + * \details H5Tget_inpad() retrieves the internal padding type for unused + * bits in floating-point datatypes. Valid padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the type of padding used for a string datatype + * + * \type_id + * + * \return Returns a valid string of the padding if successful; otherwise + * returns #H5T_STR_ERROR (-1) + * + * \details H5Tget_strpad() retrieves the type of padding used for a string + * datatype. + * + * The string padding type is set with H5Tset_strpad(). Possible + * values returned are: + * \str_pad_type + * + * \since 1.2.0 + * + */ +H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); +/** + * \ingroup COMPOUND ENUM + * + * \brief Retrieves the number of elements in a compound or enumeration datatype + * + * \type_id + * + * \return Returns the number of elements if successful; otherwise returns a + * negative value. + * + * \details H5Tget_nmembers() retrieves the number of fields in a compound + * datatype or the number of members of an enumeration datatype. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_nmembers(hid_t type_id); +/** + * \ingroup COMPOUND ENUM + * + * \brief Retrieves the name of a compound or enumeration datatype member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns a valid pointer to a string allocated with malloc() if + * successful; otherwise returns NULL. + * + * \details H5Tget_member_name() retrieves the name of a field of a compound + * datatype or an element of an enumeration datatype. + * + * The index of the target field or element is specified in \p + * member_no. Compound datatype fields and enumeration datatype + * elements are stored in no particular order with index values of + * 0 through N-1, where N is the value returned by H5Tget_nmembers(). + * + * The HDF5 library allocates a buffer to receive the name of + * the field. The caller must subsequently free the buffer with + * H5free_memory(). + * + * \since 1.2.0 + * + */ +H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno); +/** + * \ingroup COMPOUND ENUM + * + * \brief Retrieves the index of a compound or enumeration datatype member + * + * \type_id + * \param[in] name Name of the field or member + * + * \return \herr_t + * + * \details H5Tget_member_index() retrieves the index of a field of a compound + * datatype or an element of an enumeration datatype. + * + * The name of the target field or element is specified by \p name. + * + * Fields are stored in no particular order with index values of 0 + * through N-1, where N is the value returned by H5Tget_nmembers() . + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_member_index(hid_t type_id, const char *name); +/** + * \ingroup COMPOUND + * + * \brief Retrieves the offset of a field of a compound datatype + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the byte offset of the field if successful; otherwise + * returns 0 (zero). + * + * \details H5Tget_member_offset() retrieves the byte offset of the beginning + * of a field within a compound datatype with respect to the beginning + * of the compound datatype datum. + * + * Note that zero is a valid offset and that this function will fail + * only if a call to H5Tget_member_class() fails with the same arguments. + * + * \version 1.6.4 \p member_no parameter type changed to unsigned. + * + * \since 1.2.0 + * + */ +H5_DLL size_t H5Tget_member_offset(hid_t type_id, unsigned membno); +/** + * \ingroup COMPOUND + * + * \brief Returns datatype class of compound datatype member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the datatype class, a non-negative value, if successful; + * otherwise returns a negative value. + * + * \details Given a compound datatype, \p dtype_id, H5Tget_member_class() + * returns the datatype class of the member specified by \p member_no. + * + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \since 1.2.0 + * + */ H5_DLL H5T_class_t H5Tget_member_class(hid_t type_id, unsigned membno); -H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno); -H5_DLL herr_t H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/); -H5_DLL H5T_cset_t H5Tget_cset(hid_t type_id); -H5_DLL htri_t H5Tis_variable_str(hid_t type_id); -H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); +/** + * \ingroup COMPOUND + * + * \brief Returns the datatype of the specified member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the identifier of a copy of the datatype of the field if + * successful; otherwise returns a negative value. + * + * \details H5Tget_member_type() returns the datatype of the specified member. + * The caller should invoke H5Tclose() to release resources associated + * with the type. + * + * \version 1.6.4 \p membno parameter type changed to unsigned. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno); +/** + * \ingroup ENUM + * + * \brief Returns the value of an enumeration datatype member + * + * \type_id + * \param[in] membno Number of the enumeration datatype member + * \param[out] value Buffer for the value of the enumeration datatype member + * + * \return \herr_t + * + * \details H5Tget_member_value() returns the value of the enumeration datatype + * member \p member_no. + * + * The member value is returned in a user-supplied buffer pointed to + * by \p value. Values returned in \p value will be of the enumerated + * type’s base type, that is, the datatype used by H5Tenum_create() + * when the enumerated type was created. + * + * The value buffer must be at least large enough to hold a value + * of that base type. If the size is unknown, you can determine it + * with H5Tget_size(). + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the character set type of a string datatype + * + * \type_id + * + * \return Returns a valid character set type if successful; otherwise + * #H5T_CSET_ERROR (-1). + * + * \details H5Tget_cset() retrieves the character set type of a string datatype. + * Valid character set types are: + * \csets + * + * \since 1.2.0 + * + */ +H5_DLL H5T_cset_t H5Tget_cset(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Determines whether datatype is a variable-length string + * + * \type_id + * + * \return Returns: + * \li a positive value if the specified datatype is a variable-length + * string + * \li 0 if the specified datatype is not a variable-length string + * \li a negative value when the function fails + * + * \details H5Tis_variable_str() determines whether the datatype identified + * by \p dtype_id is a variable-length string. + * + * This function can be used to distinguish between fixed and + * variable-length string datatypes. + * + * \since 1.6.0 + * + */ +H5_DLL htri_t H5Tis_variable_str(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Returns the native datatype identifier of a specified datatype + * + * \type_id + * \param[in] direction Direction of search + * + * \return \hid_t{native datatype} + * + * \details H5Tget_native_type() returns the equivalent native datatype + * identifier for the datatype specified by \p type_id. + * + * H5Tget_native_type() is designed primarily to facilitate use of + * the H5Dread() function, for which users otherwise must undertake a + * multi-step process to determine the native datatype of a dataset + * prior to reading it into memory. This function can be used for + * the following purposes: + * + * \li To determine the native datatype of an atomic datatype + * \li To determine the base datatype of an array, enumerated, or + * variable-length datatype + * \li To determine the native atomic datatypes of the individual + * components of a compound datatype + * + * For example, if \p type_id is a compound datatype, the returned + * datatype identifier will be for a similar compound datatype with + * each element converted to the corresponding native datatype; + * nested compound datatypes will be unwound. If \p type_id is an + * array, the returned datatype identifier will be for the native + * datatype of a single array element. + * + * H5Tget_native_type() selects the first matching native datatype + * from the following list: + * + * \li #H5T_NATIVE_CHAR + * \li #H5T_NATIVE_SHORT + * \li #H5T_NATIVE_INT + * \li #H5T_NATIVE_LONG + * \li #H5T_NATIVE_LLONG + * + * \li #H5T_NATIVE_UCHAR + * \li #H5T_NATIVE_USHORT + * \li #H5T_NATIVE_UINT + * \li #H5T_NATIVE_ULONG + * \li #H5T_NATIVE_ULLONG + * + * \li #H5T_NATIVE_FLOAT + * \li #H5T_NATIVE_DOUBLE + * \li #H5T_NATIVE_LDOUBLE + * + * \li #H5T_NATIVE_B8 + * \li #H5T_NATIVE_B16 + * \li #H5T_NATIVE_B32 + * \li #H5T_NATIVE_B64 + * + * The direction parameter indicates the order in which the library + * searches for a native datatype match. Valid values for direction + * are as follows: + * \snippet this H5T_direction_t_snip + * + * H5Tget_native_type() is designed primarily for use with integer, + * floating point, and bitfield datatypes. String, time, opaque, and + * reference datatypes are returned as a copy of dtype_id. See above + * for compound, array, enumerated, and variable-length datatypes. + * + * The identifier returned by H5Tget_native_type() should eventually + * be closed by calling H5Tclose() to release resources. + * + * \note Please note that a datatype is actually an object + * identifier or handle returned from opening the datatype. It + * is not persistent and its value can be different from one HDF5 + * session to the next. + * + * \note H5Tequal() can be used to compare datatypes. + * + * \note HDF5 High Level APIs that may also be of interest are: H5LTdtype_to_text() + * creates a text description of a datatype. H5LTtext_to_dtype() creates an + * HDF5 datatype given a text description. + * + * \since 1.6.0 + * + */ +H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); /* Setting property values */ +/** + * \ingroup H5T + * + * \brief Sets size for a datatype. + * + * \type_id + * \param[in] size New datatype size is bytes or #H5T_VARIABLE + * + * \return \herr_t + * + * \details H5Tset_size() sets the total size, \p size, in bytes, for a + * datatype. + * + * \p size must have a positive value, unless it is passed in as + * #H5T_VARIABLE and the datatype is a string datatype. + * + * \li Numeric datatypes: If the datatype is atomic and the size + * is decreased so that significant bits of the datatype extend + * beyond the edge of the new size, then the offset property of the + * datatype is decreased toward zero. If the offset becomes zero + * and the significant bits of the datatype still hang over the edge + * of the new size, then the number of significant bits is decreased. + * + * \li String or character datatypes: The size set for a string + * datatype should include space for the null-terminator character, + * otherwise it will not be stored on (or retrieved from) + * disk. Adjusting the size of a string automatically sets the + * precision to \p 8*size. + * + * \li Variable-length string datatypes: If \p dtype_id is a + * variable-length string, size must normally be set to #H5T_VARIABLE. + * See \ref_vlen_strings. + * + * \li Compound datatypes: This function may be used to increase or + * decrease the size of a compound datatype, but the function will + * fail if the new size is too small to accommodate all member fields. + * + * \li Ineligible datatypes: This function cannot be used with + * enumerated datatypes (#H5T_ENUM), array datatypes (#H5T_ARRAY), + * variable-length array datatypes (#H5T_VLEN), or reference datatypes + * (#H5T_REFERENCE). + * + * \see H5Tget_size() + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size); +/** + * \ingroup ATOM + * + * \brief Sets the byte order of a datatype + * + * \type_id + * \param[in] order Byte order constant + * + * \return \herr_t + * + * \details H5Tset_order() sets the byte order of a datatype.\n + * Byte order can currently be set to any of the following: + * \snippet this H5T_order_t_snip + * #H5T_ORDER_MIXED (3) is a valid value for order only when + * returned by the function H5Tget_order(); it cannot be set with + * H5Tset_order(). + * + * #H5T_ORDER_NONE (4) is a valid value for order, but it has no + * effect. It is valid only for fixed-length strings and object and + * region references and specifies “no particular order.” + * + * The byte order of a derived datatype is initially the same as + * that of the parent type, but can be changed with H5Tset_order(). + * + * This function cannot be used with a datatype after it has been + * committed. + * + * \note Special considerations: + * \li ENUM datatypes: Byte order must be set before any member on + * an ENUM is defined. + * \li Compound datatypes: Byte order is set individually on each member + * of a compound datatype; members of a compound datatype need not + * have the same byte order. + * \li Opaque datatypes: Byte order can be set but has no effect. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_order(hid_t type_id, H5T_order_t order); +/** + * \ingroup ATOM + * + * \brief Sets the precision of an atomic datatype + * + * \type_id + * \param[in] prec Number of bits of precision for datatype + * + * \return \herr_t + * + * \details H5Tset_precision() sets the precision of an atomic datatype. The + * precision is the number of significant bits which, unless + * padding is present, is 8 times larger than the value returned + * by H5Tget_size(). + * + * If the precision is increased then the offset is decreased and + * then the size is increased to insure that significant bits do not + * "hang over" the edge of the datatype. + * + * Changing the precision of an #H5T_STRING automatically changes + * the size as well. The precision must be a multiple of 8. + * + * When decreasing the precision of a floating point type, set the + * locations and sizes of the sign, mantissa, and exponent fields + * first. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec); +/** + * \ingroup ATOM + * + * \brief Sets the bit offset of the first significant bit + * + * \type_id + * \param[in] offset Offset of first significant bit + * + * \return \herr_t + * + * \details H5Tset_offset() sets the bit offset of the first significant + * bit. The significant bits of an atomic datum can be offset from + * the beginning of the memory for that datum by an amount of + * padding. The offset property specifies the number of bits of + * padding that appear “to the right of” the value. That is, + * if we have a 32-bit datum with 16-bits of precision having the + * value 0x1122, then it will be laid out in memory as (from small + * byte address toward larger byte addresses): + * \code{.unparsed} + * 0: [ pad] [0x11] [0x22] [ pad] + * 1: [ pad] [0x22] [0x11] [ pad] + * 2: [0x11] [ pad] [ pad] [0x22] + * 3: [0x22] [ pad] [ pad] [0x11] + * \endcode + * If the offset is incremented then the total size is incremented + * also if necessary to prevent significant bits of the value from + * hanging over the edge of the datatype. + * + * The offset of an #H5T_STRING cannot be set to anything but zero. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_offset(hid_t type_id, size_t offset); +/** + * \ingroup ATOM + * + * \brief Sets the least and most-significant bits padding types + * + * \type_id + * \param[in] lsb Padding type for least-significant bits + * \param[in] msb Padding type for most-significant bits + * + * \return \herr_t + * + * \details H5Tset_pad() sets the least and most-significant bits padding types. + * Available values are: + * \padding_type + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb); +/** + * \ingroup ATOM + * + * \brief Sets the sign property for an integer type + * + * \type_id + * \param[in] sign Sign type + * + * \return \herr_t + * + * \details H5Tset_sign() sets the sign property for an integer type: + * \sign_prop + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign); +/** + * \ingroup ATOM + * + * \brief Sets locations and sizes of floating point bit fields + * + * \type_id + * \param[in] spos Sign position, i.e., the bit offset of the floating-point + * sign bit + * \param[in] epos Exponent bit position + * \param[in] esize Size of exponent in bits + * \param[in] mpos Mantissa bit position + * \param[in] msize Size of mantissa in bits + * + * \return \herr_t + * + * \details H5Tset_fields() sets the locations and sizes of the various + * floating-point bit fields. The field positions are bit positions + * in the significant region of the datatype. Bits are numbered with + * the least significant bit number zero. + * + * Fields are not allowed to extend beyond the number of bits of + * precision, nor are they allowed to overlap with one another. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_fields(hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize); +/** + * \ingroup ATOM + * + * \brief Sets the exponent bias of a floating-point type + * + * \type_id + * \param[in] ebias Exponent bias value + * + * \return \herr_t + * + * \details H5Tset_ebias() sets the exponent bias of a floating-point type. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_ebias(hid_t type_id, size_t ebias); +/** + * \ingroup ATOM + * + * \brief Sets the mantissa normalization of a floating-point datatype + * + * \type_id + * \param[in] norm Mantissa normalization type + * + * \return \herr_t + * + * \details H5Tset_norm() sets the mantissa normalization of a floating-point + * datatype. Valid normalization types are: + * \snippet this H5T_norm_t_snip + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_norm(hid_t type_id, H5T_norm_t norm); +/** + * \ingroup ATOM + * + * \brief Fills unused internal floating-point bits + * + * \type_id + * \param[in] pad Padding type + * + * \return \herr_t + * + * \details H5Tset_inpad() If any internal bits of a floating point-type are + * unused (that is, those significant bits which are not part of the + * sign, exponent, or mantissa), then H5Tset_inpad() will be filled + * according to the value of the padding value property inpad. Valid + * padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t pad); +/** + * \ingroup ATOM + * + * \brief Sets character set to be used in a string or character datatype + * + * \type_id + * \param[in] cset Character set type + * + * \return \herr_t + * + * \details H5Tset_cset() sets the character set to be used in a dataset with + * a string or character datatype. + * + * Valid values for cset include the following: + * \csets + * For example, if the character set for the datatype \p type_id is set + * to #H5T_CSET_UTF8, string or character data of datatype dtype_id + * will be encoded using the UTF-8 Unicode character set. + * + * ASCII and UTF-8 Unicode are the only currently supported character + * encodings. Extended ASCII encodings (for example, ISO 8859) are + * not supported. This encoding policy is not enforced by the HDF5 + * library. Using encodings other than ASCII and UTF-8 can lead to + * compatibility and usability problems. + * + * Note that H5Tset_cset() sets the character set for a character or + * string datatype while H5Pset_char_encoding() sets the character + * set used for an HDF5 link or attribute name. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset); +/** + * \ingroup ATOM + * + * \brief Defines the type of padding used for character strings + * + * \type_id + * \param[in] strpad String padding type + * + * \return \herr_t + * + * \details H5Tset_strpad() defines the type of padding used for a string + * datatype. + * + * The method used to store character strings differs with the + * programming language. C usually null terminates strings while + * Fortran left-justifies and space-pads strings. + * + * Valid values of \p strpad are as follows: + * \str_pad_type + * When converting from a longer string to a shorter string, the + * behavior is as follows. If the shorter string is #H5T_STR_NULLPAD + * or #H5T_STR_SPACEPAD, then the string is simply truncated. If + * the short string is #H5T_STR_NULLTERM, it is truncated and a null + * terminator is appended. + * + * When converting from a shorter string to a longer string, the + * longer string is padded on the end by appending nulls or spaces. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad); /* Type conversion database */ +/** + * \ingroup CONV + * + * \brief Registers a datatype conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tregister() registers a hard or soft conversion function for a + * datatype conversion path. The parameter \p pers indicates whether a + * conversion function is hard (#H5T_PERS_HARD) or soft + * (#H5T_PERS_SOFT). User-defined functions employing compiler casting + * are designated as \Emph{hard}; other user-defined conversion + * functions registered with the HDF5 library (with H5Tregister() ) + * are designated as \Emph{soft}. The HDF5 library also has its own + * hard and soft conversion functions. + * + * A conversion path can have only one hard function. When type is + * #H5T_PERS_HARD, \p func replaces any previous hard function. + * + * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the + * end of the master soft list and replaces the soft function in all + * applicable existing conversion paths. Soft functions are used when + * determining which conversion function is appropriate for this path. + * + * The \p name is used only for debugging and should be a short + * identifier for the function. + * + * The path is specified by the source and destination datatypes \p + * src_id and \p dst_id. For soft conversion functions, only the class + * of these types is important. + * + * The type of the conversion function pointer is declared as: + * \snippet this H5T_conv_t_snip + * + * The \ref H5T_cdata_t \c struct is declared as: + * \snippet this H5T_cdata_t_snip + * + * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Removes a conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tunregister() removes a conversion function matching criteria + * such as soft or hard conversion, source and destination types, and + * the conversion function. + * + * If a user is trying to remove a conversion function he registered, + * all parameters can be used. If he is trying to remove a library’s + * default conversion function, there is no guarantee the \p name and + * \p func parameters will match the user’s chosen values. Passing in + * some values may cause this function to fail. A good practice is to + * pass in NULL as their values. + * + * All parameters are optional. The missing parameters will be used to + * generalize the search criteria. + * + * The conversion function pointer type declaration is described in + * H5Tregister(). + * + * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Finds a conversion function + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[out] pcdata Pointer to type conversion data + * + * \return Returns a pointer to a suitable conversion function if successful. + * Otherwise returns NULL. + * + * \details H5Tfind() finds a conversion function that can handle a conversion + * from type \p src_id to type \p dst_id. The \p pcdata argument is a + * pointer to a pointer to type conversion data which was created and + * initialized by the soft type conversion function of this path when + * the conversion function was installed on the path. + * + */ H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata); -H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); -H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, - hid_t plist_id); +/** + * \ingroup CONV + * + * \brief Check whether the library’s default conversion is hard conversion + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * + * \return \htri_t + * + * \details H5Tcompiler_conv() determines whether the library’s conversion + * function from type \p src_id to type \p dst_id is a compiler (hard) + * conversion or not. A compiler conversion uses compiler’s casting; a + * library (soft) conversion uses the library’s own conversion + * function. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); +/** + * -------------------------------------------------------------------------- + * \ingroup CONV + * + * \brief Converts data from one specified datatype to another + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] nelmts Size of array \p buf + * \param[in,out] buf Array containing pre- and post-conversion values + * \param[in] background Optional background buffer + * \dxpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Tconvert() converts \p nelmts elements from a source datatype, + * specified by \p src_id, to a destination datatype, \p dst_id. The + * source elements are packed in \p buf and on return the destination + * elements will be packed in \p buf. That is, the conversion is + * performed in place. + * + * The optional background buffer is for use with compound datatypes. + * It is an array of \p nelmts values for the destination datatype + * which can then be merged with the converted values to recreate the + * compound datatype. For instance, background might be an array of + * structs with the \c a and \c b fields already initialized and the + * conversion of buf supplies the \c c and \c d field values. + * + * The parameter \p plist_id contains the dataset transfer property list + * identifier which is passed to the conversion functions. As of + * Release 1.2, this parameter is only used to pass along the + * variable-length datatype custom allocation information. + * + * \note H5Tconvert() will not resize the buffer \p buf; it must be large + * enough to hold the larger of the input and output data. + * + * \version 1.6.3 \p nelmts parameter type changed to size_t. + * \version 1.4.0 \p nelmts parameter type changed to hsize_t. + * + */ +H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, + hid_t plist_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. */ + #ifndef H5_NO_DEPRECATED_SYMBOLS /* Macros */ @@ -593,11 +2797,140 @@ H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *bu /* Typedefs */ /* Function prototypes */ +/** + * \ingroup H5T + * + * \brief Commits a transient datatype to a file, creating a new named datatype + * + * \fg_loc_id + * \param[in] name Name given to committed datatype + * \param[in] type_id Identifier of datatype to be committed + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Tcommit() and is + * deprecated in favor of the macro #H5Tcommit or the function + * H5Tcommit2(). + * + * \details H5Tcommit1() commits the transient datatype (not immutable) to + * a file, turning it into a named datatype. + * + * The datatype \p dtype_id is committed as a named datatype at the + * location \p loc_id, which is either a file or group identifier, + * with the name \p name. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires + * that any intermediate groups specified in the path already exist. + * + * As is the case for any object in a group, the length of the name + * of a named datatype is not limited. + * + * See H5Tcommit_anon() for a discussion of the differences between + * H5Tcommit() and H5Tcommit_anon(). + * + * This function will not accept a datatype that cannot actually + * hold data. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accommodate actual data, such as a compound datatype with + * no fields or an enumerated datatype with no members. + * \version 1.8.0 C function H5Tcommit() renamed to H5Tcommit1() and deprecated + * in this release. + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tcommit1(hid_t loc_id, const char *name, hid_t type_id); -H5_DLL hid_t H5Topen1(hid_t loc_id, const char *name); -H5_DLL hid_t H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */], - const int perm[/* ndims */]); -H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]); +/** + * \ingroup H5T + * + * \brief Opens a named datatype + * + * \fg_loc_id + * \param[in] name A datatype name, defined within the specified file or group + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Topen() and is + * deprecated in favor of the macro #H5Topen or the function + * H5Topen2(). + * + * \details H5Topen1() opens a named datatype at the location specified by + * \p loc_id and returns an identifier for the datatype. \p loc_id + * can be either a file or group identifier. The identifier should + * eventually be closed by calling H5Tclose() to release resources. + * + * \version 1.8.0 Function H5Topen() renamed to H5Topen1() and deprecated in + * this release. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Topen1(hid_t loc_id, const char *name); +/** + * \ingroup ARRAY + * + * \brief Creates an array datatype object + * + * \param[in] base_id Datatype identifier for the array base datatype + * \param[in] ndims Rank of the array + * \param[in] dim Size of each array dimension + * \param[in] perm Dimension permutation (Currently not implemented.) + * + * \return \hid_t{array datatype} + * + * \deprecated This function has been renamed from H5Tarray_create() and is + * deprecated in favor of the macro #H5Tarray_create or the function + * H5Tarray_create2(). + * + * \details H5Tarray_create1() creates a new array datatype object.\n\n + * \p base_id is the datatype of every element of the array, i.e., + * of the number at each position in the array. + * + * \p rank is the number of dimensions and the size of each dimension + * is specified in the array dims. The value of rank is currently + * limited to #H5S_MAX_RANK and must be greater than 0 (zero). All + * dimension sizes specified in dims must be greater than 0 (zero). + * + * The array \p perm is designed to contain the dimension permutation, + * i.e. C versus FORTRAN array order. (The parameter perm is + * currently unused and is not yet implemented.) + * + * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1() + * and deprecated in this release. + * \since 1.4.0 + * + */ +H5_DLL hid_t H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */], + const int perm[/* ndims */]); +/** + * \ingroup ARRAY + * + * \brief Retrieves sizes of array dimensions + * + * \type_id + * \param[out] dims Sizes of array dimensions + * \param[out] perm Dimension permutations (This parameter is not used.) + * + * \return Returns the non-negative number of dimensions of the array type + * if successful; otherwise, returns a negative value. + * + * \deprecated This function has been renamed from H5Tget_array_dims() and is + * deprecated in favor of the macro #H5Tget_array_dims or the + * function H5Tget_array_dims2(). + * + * \details H5Tget_array_dims1() returns the sizes of the dimensions and + * the dimension permutations of the specified array datatype object. + * + * The sizes of the dimensions are returned in the array \p dims. + * + * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1() + * and deprecated in this release. + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index e829eb1..90277cf 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -21,111 +21,231 @@ /* Public headers needed by this file */ #include "H5public.h" -/* - * Filter identifiers. Values 0 through 255 are for filters defined by the - * HDF5 library. Values 256 through 511 are available for testing new - * filters. Subsequent values should be obtained from the HDF5 development - * team at help@hdfgroup.org. These values will never change because they - * appear in the HDF5 files. +/** + * \brief Filter identifiers + * + * \details Values 0 through 255 are for filters defined by the HDF5 library. + * Values 256 through 511 are available for testing new filters. + * Subsequent values should be obtained from the HDF5 development team + * at mailto:help@hdfgroup.org. These values will never change because + * they appear in the HDF5 files. */ typedef int H5Z_filter_t; /* Filter IDs */ -#define H5Z_FILTER_ERROR (-1) /*no filter */ -#define H5Z_FILTER_NONE 0 /*reserved indefinitely */ -#define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */ -#define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */ -#define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */ -#define H5Z_FILTER_SZIP 4 /*szip compression */ -#define H5Z_FILTER_NBIT 5 /*nbit compression */ -#define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */ -#define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */ - -#define H5Z_FILTER_MAX 65535 /*maximum filter id */ +/** + * no filter + */ +#define H5Z_FILTER_ERROR (-1) +/** + * reserved indefinitely + */ +#define H5Z_FILTER_NONE 0 +/** + * deflation like gzip + */ +#define H5Z_FILTER_DEFLATE 1 +/** + * shuffle the data + */ +#define H5Z_FILTER_SHUFFLE 2 +/** + * fletcher32 checksum of EDC + */ +#define H5Z_FILTER_FLETCHER32 3 +/** + * szip compression + */ +#define H5Z_FILTER_SZIP 4 +/** + * nbit compression + */ +#define H5Z_FILTER_NBIT 5 +/** + * scale+offset compression + */ +#define H5Z_FILTER_SCALEOFFSET 6 +/** + * filter ids below this value are reserved for library use + */ +#define H5Z_FILTER_RESERVED 256 +/** + * maximum filter id + */ +#define H5Z_FILTER_MAX 65535 /* General macros */ -#define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */ -#define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */ - /* (should probably be allowed to be an - * unlimited amount, but currently each - * filter uses a bit in a 32-bit field, - * so the format would have to be - * changed to accommodate that) - */ +/** + * Symbol to remove all filters in H5Premove_filter() + */ +#define H5Z_FILTER_ALL 0 +/** + * Maximum number of filters allowed in a pipeline + * + * \internal (should probably be allowed to be an unlimited amount, but + * currently each filter uses a bit in a 32-bit field, so the format + * would have to be changed to accommodate that) + */ +#define H5Z_MAX_NFILTERS 32 /* Flags for filter definition (stored) */ -#define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */ -#define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */ -#define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */ +/** + * definition flag mask + */ +#define H5Z_FLAG_DEFMASK 0x00ff +/** + * filter is mandatory + */ +#define H5Z_FLAG_MANDATORY 0x0000 +/** + * filter is optional + */ +#define H5Z_FLAG_OPTIONAL 0x0001 /* Additional flags for filter invocation (not stored) */ -#define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */ -#define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */ -#define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */ +/** + * invocation flag mask + */ +#define H5Z_FLAG_INVMASK 0xff00 +/** + * reverse direction; read + */ +#define H5Z_FLAG_REVERSE 0x0100 +/** + * skip EDC filters for read + */ +#define H5Z_FLAG_SKIP_EDC 0x0200 /* Special parameters for szip compression */ /* [These are aliases for the similar definitions in szlib.h, which we can't * include directly due to the duplication of various symbols with the zlib.h * header file] */ +/** + * \ingroup SZIP */ #define H5_SZIP_ALLOW_K13_OPTION_MASK 1 -#define H5_SZIP_CHIP_OPTION_MASK 2 -#define H5_SZIP_EC_OPTION_MASK 4 -#define H5_SZIP_NN_OPTION_MASK 32 -#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_CHIP_OPTION_MASK 2 +/** + * \ingroup SZIP */ +#define H5_SZIP_EC_OPTION_MASK 4 +/** + * \ingroup SZIP */ +#define H5_SZIP_NN_OPTION_MASK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 /* Macros for the shuffle filter */ -#define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */ -#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */ +/** + * \ingroup SHUFFLE + * Number of parameters that users can set for the shuffle filter + */ +#define H5Z_SHUFFLE_USER_NPARMS 0 +/** + * \ingroup SHUFFLE + * Total number of parameters for the shuffle filter + */ +#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Macros for the szip filter */ -#define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */ -#define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */ -#define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */ -#define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */ -#define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */ -#define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */ +/** + * \ingroup SZIP + * Number of parameters that users can set for SZIP + */ +#define H5Z_SZIP_USER_NPARMS 2 +/** + * \ingroup SZIP + * Total number of parameters for SZIP filter + */ +#define H5Z_SZIP_TOTAL_NPARMS 4 +/** + * \ingroup SZIP + * "User" parameter for option mask + */ +#define H5Z_SZIP_PARM_MASK 0 +/** + * \ingroup SZIP + * "User" parameter for pixels-per-block + */ +#define H5Z_SZIP_PARM_PPB 1 +/** + * \ingroup SZIP + * "Local" parameter for bits-per-pixel + */ +#define H5Z_SZIP_PARM_BPP 2 +/** + * \ingroup SZIP + * "Local" parameter for pixels-per-scanline + */ +#define H5Z_SZIP_PARM_PPS 3 /* Macros for the nbit filter */ +/** + * \ingroup NBIT + * Number of parameters that users can set for the N-bit filter + */ #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ /* Macros for the scale offset filter */ -#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */ +/** + * \ingroup SCALEOFFSET + * Number of parameters that users can set for the scale-offset filter + */ +#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Special parameters for ScaleOffset filter*/ +/** + * \ingroup SCALEOFFSET */ #define H5Z_SO_INT_MINBITS_DEFAULT 0 +/** + * \ingroup SCALEOFFSET */ typedef enum H5Z_SO_scale_type_t { H5Z_SO_FLOAT_DSCALE = 0, H5Z_SO_FLOAT_ESCALE = 1, H5Z_SO_INT = 2 } H5Z_SO_scale_type_t; -/* Current version of the H5Z_class_t struct */ +/** + * Current version of the H5Z_class_t struct + */ #define H5Z_CLASS_T_VERS (1) -/* Values to decide if EDC is enabled for reading data */ +/** + * \ingroup FLETCHER32 + * Values to decide if EDC is enabled for reading data + */ typedef enum H5Z_EDC_t { - H5Z_ERROR_EDC = -1, /* error value */ + H5Z_ERROR_EDC = -1, /**< error value */ H5Z_DISABLE_EDC = 0, H5Z_ENABLE_EDC = 1, - H5Z_NO_EDC = 2 /* must be the last */ + H5Z_NO_EDC = 2 /**< sentinel */ } H5Z_EDC_t; /* Bit flags for H5Zget_filter_info */ #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001) #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002) -/* Return values for filter callback function */ +/** + * Return values for filter callback function + */ typedef enum H5Z_cb_return_t { - H5Z_CB_ERROR = -1, - H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */ - H5Z_CB_CONT = 1, /* I/O continues if filter fails. */ - H5Z_CB_NO = 2 + H5Z_CB_ERROR = -1, /**< error value */ + H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ + H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ + H5Z_CB_NO = 2 /**< sentinel */ } H5Z_cb_return_t; -/* Filter callback function definition */ +//! <!-- [H5Z_filter_func_t_snip] --> +/** + * Filter callback function definition + */ typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); +//! <!-- [H5Z_filter_func_t_snip] --> -/* Structure for filter callback property */ +/** + * Structure for filter callback property + */ typedef struct H5Z_cb_t { H5Z_filter_func_t func; void * op_data; @@ -135,87 +255,411 @@ typedef struct H5Z_cb_t { extern "C" { #endif -/* - * Before a dataset gets created, the "can_apply" callbacks for any filters used - * in the dataset creation property list are called - * with the dataset's dataset creation property list, the dataset's datatype and - * a dataspace describing a chunk (for chunked dataset storage). +/** + * \brief This callback determines if a filter can be applied to the dataset + * with the characteristics provided + * + * \dcpl_id + * \type_id + * \space_id + * + * \return \htri_t * - * The "can_apply" callback must determine if the combination of the dataset - * creation property list setting, the datatype and the dataspace represent a - * valid combination to apply this filter to. For example, some cases of - * invalid combinations may involve the filter not operating correctly on - * certain datatypes (or certain datatype sizes), or certain sizes of the chunk - * dataspace. + * \details Before a dataset gets created, the \ref H5Z_can_apply_func_t + * callbacks for any filters used in the dataset creation property list + * are called with the dataset's dataset creation property list, the + * dataset's datatype and a dataspace describing a chunk (for chunked + * dataset storage). * - * The "can_apply" callback can be the NULL pointer, in which case, the library - * will assume that it can apply to any combination of dataset creation - * property list values, datatypes and dataspaces. + * The \ref H5Z_can_apply_func_t callback must determine if the + * combination of the dataset creation property list setting, the + * datatype and the dataspace represent a valid combination to apply + * this filter to. For example, some cases of invalid combinations may + * involve the filter not operating correctly on certain datatypes (or + * certain datatype sizes), or certain sizes of the chunk dataspace. * - * The "can_apply" callback returns positive a valid combination, zero for an - * invalid combination and negative for an error. + * The \ref H5Z_can_apply_func_t callback can be the NULL pointer, in + * which case, the library will assume that it can apply to any + * combination of dataset creation property list values, datatypes and + * dataspaces. + * + * The \ref H5Z_can_apply_func_t callback returns positive a valid + * combination, zero for an invalid combination and negative for an + * error. */ +//! <!-- [H5Z_can_apply_func_t_snip] --> typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); - -/* - * After the "can_apply" callbacks are checked for new datasets, the "set_local" - * callbacks for any filters used in the dataset creation property list are - * called. These callbacks receive the dataset's private copy of the dataset - * creation property list passed in to H5Dcreate (i.e. not the actual property - * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate - * (which is not copied and should not be modified) and a dataspace describing - * the chunk (for chunked dataset storage) (which should also not be modified). +//! <!-- [H5Z_can_apply_func_t_snip] --> +/** + * \brief The filter operation callback function, defining a filter's operation + * on data + * + * \dcpl_id + * \type_id + * \space_id * - * The "set_local" callback must set any parameters that are specific to this - * dataset, based on the combination of the dataset creation property list - * values, the datatype and the dataspace. For example, some filters perform - * different actions based on different datatypes (or datatype sizes) or - * different number of dimensions or dataspace sizes. + * \return \herr_t * - * The "set_local" callback can be the NULL pointer, in which case, the library - * will assume that there are no dataset-specific settings for this filter. + * \details After the \ref H5Z_can_apply_func_t callbacks are checked for new + * datasets, the \ref H5Z_set_local_func_t callbacks for any filters + * used in the dataset creation property list are called. These + * callbacks receive the dataset's private copy of the dataset creation + * property list passed in to H5Dcreate() (i.e. not the actual property + * list passed in to H5Dcreate()) and the datatype ID passed in to + * H5Dcreate() (which is not copied and should not be modified) and a + * dataspace describing the chunk (for chunked dataset storage) (which + * should also not be modified). * - * The "set_local" callback must return non-negative on success and negative - * for an error. + * The \ref H5Z_set_local_func_t callback must set any parameters that + * are specific to this dataset, based on the combination of the + * dataset creation property list values, the datatype and the + * dataspace. For example, some filters perform different actions based + * on different datatypes (or datatype sizes) or different number of + * dimensions or dataspace sizes. + * + * The \ref H5Z_set_local_func_t callback can be the NULL pointer, in + * which case, the library will assume that there are no + * dataset-specific settings for this filter. + * + * The \ref H5Z_set_local_func_t callback must return non-negative on + * success and negative for an error. */ +//! <!-- [H5Z_set_local_func_t_snip] --> typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); +//! <!-- [H5Z_set_local_func_t_snip] --> -/* - * A filter gets definition flags and invocation flags (defined above), the - * client data array and size defined when the filter was added to the - * pipeline, the size in bytes of the data on which to operate, and pointers - * to a buffer and its allocated size. +/** + * \brief The filter operation callback function, defining a filter's operation + * on data + * + * \param[in] flags Bit vector specifying certain general properties of the filter + * \param[in] cd_nelmts Number of elements in \p cd_values + * \param[in] cd_values Auxiliary data for the filter + * \param[in] nbytes The number of valid bytes in \p buf to be filtered + * \param[in,out] buf_size The size of \p buf + * \param[in,out] buf The filter buffer + * + * \return Returns the number of valid bytes of data contained in \p buf. In the + * case of failure, the return value is 0 (zero) and all pointer + * arguments are left unchanged. * - * The filter should store the result in the supplied buffer if possible, - * otherwise it can allocate a new buffer, freeing the original. The - * allocated size of the new buffer should be returned through the BUF_SIZE - * pointer and the new buffer through the BUF pointer. + * \details A filter gets definition flags and invocation flags (defined + * above), the client data array and size defined when the filter was + * added to the pipeline, the size in bytes of the data on which to + * operate, and pointers to a buffer and its allocated size. * - * The return value from the filter is the number of bytes in the output - * buffer. If an error occurs then the function should return zero and leave - * all pointer arguments unchanged. + * The filter should store the result in the supplied buffer if + * possible, otherwise it can allocate a new buffer, freeing the + * original. The allocated size of the new buffer should be returned + * through the \p buf_size pointer and the new buffer through the \p + * buf pointer. + * + * The return value from the filter is the number of bytes in the + * output buffer. If an error occurs then the function should return + * zero and leave all pointer arguments unchanged. */ +//! <!-- [H5Z_func_t_snip] --> typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf); - -/* +//! <!-- [H5Z_func_t_snip] --> +/** * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ +//! <!-- [H5Z_class2_t_snip] --> typedef struct H5Z_class2_t { - int version; /* Version number of the H5Z_class_t struct */ - H5Z_filter_t id; /* Filter ID number */ - unsigned encoder_present; /* Does this filter have an encoder? */ - unsigned decoder_present; /* Does this filter have a decoder? */ - const char * name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ + int version; /**< Version number of the H5Z_class_t struct */ + H5Z_filter_t id; /**< Filter ID number */ + unsigned encoder_present; /**< Does this filter have an encoder? */ + unsigned decoder_present; /**< Does this filter have a decoder? */ + const char * name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ + H5Z_func_t filter; /**< The actual filter function */ } H5Z_class2_t; +//! <!-- [H5Z_class2_t_snip] --> +/** + * \ingroup H5Z + * + * \brief Registers a new filter with the HDF5 library + * + * \param[in] cls A pointer to a buffer for the struct containing the + * filter-definition + * + * \return \herr_t + * + * \details H5Zregister() registers a new filter with the HDF5 library. + * + * \details Making a new filter available to an application is a two-step + * process. The first step is to write the three filter callback + * functions described below: \c can_apply, \c set_local, and \c + * filter. This call to H5Zregister(), registering the filter with the + * library, is the second step. The can_apply and set_local fields can + * be set to NULL if they are not required for the filter being + * registered. + * + * H5Zregister() accepts a single parameter, a pointer to a buffer for + * the \p cls data structure. That data structure must conform to one + * of the following definitions: + * \snippet this H5Z_class1_t_snip + * or + * \snippet this H5Z_class2_t_snip + * + * \c version is a library-defined value reporting the version number + * of the #H5Z_class_t struct. This currently must be set to + * #H5Z_CLASS_T_VERS. + * + * \c id is the identifier for the new filter. This is a user-defined + * value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These + * values are defined in the HDF5 source file H5Zpublic.h, but the + * symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be + * used instead of the literal values. + * + * \c encoder_present is a library-defined value indicating whether + * the filter’s encoding capability is available to the application. + * + * \c decoder_present is a library-defined value indicating whether + * the filter’s encoding capability is available to the application. + * + * \c name is a descriptive comment used for debugging, may contain a + * descriptive name for the filter, and may be the null pointer. + * + * \c can_apply, described in detail below, is a user-defined callback + * function which determines whether the combination of the dataset + * creation property list values, the datatype, and the dataspace + * represent a valid combination to apply this filter to. + * + * \c set_local, described in detail below, is a user-defined callback + * function which sets any parameters that are specific to this + * dataset, based on the combination of the dataset creation property + * list values, the datatype, and the dataspace. + * + * \c filter, described in detail below, is a user-defined callback + * function which performs the action of the filter. + * + * The statistics associated with a filter are not reset by this + * function; they accumulate over the life of the library. + * + * #H5Z_class_t is a macro which maps to either H5Z_class1_t or + * H5Z_class2_t, depending on the needs of the application. To affect + * only this macro, H5Z_class_t_vers may be defined to either 1 or 2. + * Otherwise, it will behave in the same manner as other API + * compatibility macros. See API Compatibility Macros in HDF5 for more + * information. H5Z_class1_t matches the #H5Z_class_t structure that is + * used in the 1.6.x versions of the HDF5 library. + * + * H5Zregister() will automatically detect which structure type has + * been passed in, regardless of the mapping of the #H5Z_class_t macro. + * However, the application must make sure that the fields are filled + * in according to the correct structure definition if the macro is + * used to declare the structure. + * + * \Bold{The callback functions:}\n Before H5Zregister() can link a + * filter into an application, three callback functions must be + * defined as described in the HDF5 library header file H5Zpublic.h. + * + * When a filter is applied to the fractal heap for a group (e.g., + * when compressing group metadata) and if the can apply and set local + * callback functions have been defined for that filter, HDF5 passes + * the value -1 for all parameters for those callback functions. This + * is done to ensure that the filter will not be applied to groups if + * it relies on these parameters, as they are not applicable to group + * fractal heaps; to operate on group fractal heaps, a filter must be + * capable of operating on an opaque block of binary data. + * + * The \Emph{can apply} callback function must return a positive value + * for a valid combination, zero for an invalid combination, and a + * negative value for an error. + * \snippet this H5Z_can_apply_func_t_snip + * + * Before a dataset is created, the \Emph{can apply} callbacks for any + * filters used in the dataset creation property list are called with + * the dataset's dataset creation property list, \c dcpl_id, the + * dataset's datatype, \p type_id, and a dataspace describing a chunk, + * \p space_id, (for chunked dataset storage). + * + * This callback must determine whether the combination of the dataset + * creation property list settings, the datatype, and the dataspace + * represent a valid combination to which to apply this filter. For + * example, an invalid combination may involve the filter not + * operating correctly on certain datatypes, on certain datatype + * sizes, or on certain sizes of the chunk dataspace. If this filter + * is enabled through H5Pset_filter() as optional and the can apply + * function returns 0, the library will skip the filter in the filter + * pipeline. + * + * This callback can be the NULL pointer, in which case the library + * will assume that the filter can be applied to a dataset with any + * combination of dataset creation property list values, datatypes, + * and dataspaces. + * + * The \Emph{set local} callback function is defined as follows: + * \snippet this H5Z_set_local_func_t_snip + * + * After the can apply callbacks are checked for a new dataset, the + * \Emph{set local} callback functions for any filters used in the + * dataset creation property list are called. These callbacks receive + * \c dcpl_id, the dataset's private copy of the dataset creation + * property list passed in to H5Dcreate() (i.e. not the actual + * property list passed in to H5Dcreate()); \c type_id, the datatype + * identifier passed in to H5Dcreate(), which is not copied and should + * not be modified; and \c space_id, a dataspace describing the chunk + * (for chunked dataset storage), which should also not be modified. + * + * The set local callback must set any filter parameters that are + * specific to this dataset, based on the combination of the dataset + * creation property list values, the datatype, and the dataspace. For + * example, some filters perform different actions based on different + * datatypes, datatype sizes, numbers of dimensions, or dataspace + * sizes. + * + * The \Emph{set local} callback may be the NULL pointer, in which + * case, the library will assume that there are no dataset-specific + * settings for this filter. + * + * The \Emph{set local} callback function must return a non-negative + * value on success and a negative value for an error. + * + * The \Emph{filter operation} callback function, defining the + * filter's operation on the data, is defined as follows: + * \snippet this H5Z_func_t_snip + * + * The parameters \c flags, \c cd_nelmts, and \c cd_values are the + * same as for the function H5Pset_filter(). The one exception is that + * an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is + * called as part of the input pipeline. + * + * The parameter \c buf points to the input buffer which has a size of + * \c buf_size bytes, \c nbytes of which are valid data. + * + * The filter should perform the transformation in place if possible. + * If the transformation cannot be done in place, then the filter + * should allocate a new buffer with malloc() and assign it to \c buf, + * assigning the allocated size of that buffer to \c buf_size. The old + * buffer should be freed by calling free(). + * + * If successful, the \Emph{filter operation} callback function + * returns the number of valid bytes of data contained in \c buf. In + * the case of failure, the return value is 0 (zero) and all pointer + * arguments are left unchanged. + * + * \version 1.8.6 Return type for the \Emph{can apply} callback function, + * \ref H5Z_can_apply_func_t, changed to \ref htri_t. + * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local} + * callback functions changed to accommodate the use of filters + * with group fractal heaps. + * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure + * introduced for backwards compatibility with release 1.6.x, + * and #H5Z_class_t macro introduced in this release. Function + * modified to accept either structure type. + * \version 1.8.0 The fields \c version, \c encoder_present, and + * \c decoder_present were added to the #H5Z_class_t \c struct + * in this release. + * \version 1.6.0 This function was substantially revised in Release 1.6.0 with + * a new #H5Z_class_t struct and new set local and can apply + * callback functions. + * + */ H5_DLL herr_t H5Zregister(const void *cls); +/** + * \ingroup H5Z + * + * \brief Unregisters a filter. + * + * \param[in] id Identifier of the filter to be unregistered. + * \return \herr_t + * + * \details H5Zunregister() unregisters the filter specified in \p id. + * + * \details This function first iterates through all opened datasets and + * groups. If an open object that uses this filter is found, the + * function will fail with a message indicating that an object using + * the filter is still open. All open files are then flushed to make + * sure that all cached data that may use this filter are written out. + * + * If the application is a parallel program, all processes that + * participate in collective data write should call this function to + * ensure that all data is flushed. + * + * After a call to H5Zunregister(), the filter specified in filter + * will no longer be available to the application. + * + * \version 1.8.12 Function modified to check for open objects using the + * filter. + * \since 1.6.0 + */ H5_DLL herr_t H5Zunregister(H5Z_filter_t id); +/** + * \ingroup H5Z + * + * \brief Determines whether a filter is available + * + * \param[in] id Filter identifier + * \return \htri_t + * + * \details H5Zfilter_avail() determines whether the filter specified in \p id + * is available to the application. + * + * \since 1.6.0 + */ H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); +/** + * \ingroup H5Z + * + * \brief Retrieves information about a filter + * + * \param[in] filter Filter identifier + * \param[out] filter_config_flags A bit field encoding the returned filter + * information + * \return \herr_t + * + * \details H5Zget_filter_info() retrieves information about a filter. At + * present, this means that the function retrieves a filter's + * configuration flags, indicating whether the filter is configured to + * decode data, to encode data, neither, or both. + * + * If \p filter_config_flags is not set to NULL prior to the function + * call, the returned parameter contains a bit field specifying the + * available filter configuration. The configuration flag values can + * then be determined through a series of bitwise AND operations, as + * described below. + * + * Valid filter configuration flags include the following: + * <table> + * <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td> + * <td>Encoding is enabled for this filter</td></tr> + * <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td> + * <td>Decoding is enabled for this filter</td></tr> + * </table> + * + * A bitwise AND of the returned \p filter_config_flags and a valid + * filter configuration flag will reveal whether the related + * configuration option is available. For example, if the value of + * \code + * H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags + * \endcode + * is true, i.e., greater than 0 (zero), the queried filter + * is configured to encode data; if the value is \c FALSE, i.e., equal to + * 0 (zero), the filter is not so configured. + * + * If a filter is not encode-enabled, the corresponding \c H5Pset_* + * function will return an error if the filter is added to a dataset + * creation property list (which is required if the filter is to be + * used to encode that dataset). For example, if the + * #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP + * filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail. + * + * If a filter is not decode-enabled, the application will not be able + * to read an existing file encoded with that filter. + * + * This function should be called, and the returned \p + * filter_config_flags analyzed, before calling any other function, + * such as H5Pset_szip() , that might require a particular filter + * configuration. + * + * \since 1.6.3 + */ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -224,17 +668,19 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi */ #ifndef H5_NO_DEPRECATED_SYMBOLS -/* +/** * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ +//! <!-- [H5Z_class1_t_snip] --> typedef struct H5Z_class1_t { - H5Z_filter_t id; /* Filter ID number */ - const char * name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ + H5Z_filter_t id; /**< Filter ID number */ + const char * name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ + H5Z_func_t filter; /**< The actual filter function */ } H5Z_class1_t; +//! <!-- [H5Z_class1_t_snip] --> #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5win32defs.h b/src/H5win32defs.h index 2fc1d80..10a5e83 100644 --- a/src/H5win32defs.h +++ b/src/H5win32defs.h @@ -11,10 +11,7 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Scott Wegner - * June 3, 2008 - * - * Purpose: This file is used to map HDF macros to Windows functions. This +/* Purpose: This file is used to map HDF macros to Windows functions. This * should get included H5private mappings, so as to override them. * Any macro not mapped here, however, will receive a similar mapping * inside H5private.h @@ -60,10 +57,11 @@ #define PRIxMAX "llx" #endif -/* - * _MSC_VER = 1900 VS2015 - * _MSC_VER = 1800 VS2013 - * _MSC_VER = 1700 VS2012 +/* _MSC_VER = 192x VS2019 + * _MSC_VER = 191x VS2017 + * _MSC_VER = 1900 VS2015 + * _MSC_VER = 1800 VS2013 + * _MSC_VER = 1700 VS2012 */ #ifdef H5_HAVE_WIN32_API @@ -127,7 +125,7 @@ typedef __int64 h5_stat_size_t; #endif /* MSC_VER < 1800 */ /* - * The (void*) cast just avoids a compiler warning in H5_HAVE_VISUAL_STUDIO + * The (void*) cast just avoids a compiler warning in MSVC */ #define HDmemset(X, C, Z) memset((void *)(X), C, Z) |
