- Length fo External File Name |
+ Length of External File Name |
This is the length for the external file name.
This field exists if bit 0 of flags is set.
diff --git a/doxygen/examples/H5E_examples.c b/doxygen/examples/H5E_examples.c
new file mode 100644
index 0000000..deea838
--- /dev/null
+++ b/doxygen/examples/H5E_examples.c
@@ -0,0 +1,97 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_push, fail_minor, fail_major, fail_class;
+ hid_t cls, major, minor;
+
+ // register a new error class for this "application"
+ if ((cls = H5Eregister_class("Custom error class", "H5E_examples", "0.1")) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_class;
+ }
+
+ // create custom major and minor error codes
+ if ((major = H5Ecreate_msg(cls, H5E_MAJOR, "Okay, Houston, we've had a problem here")) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_major;
+ }
+ if ((minor = H5Ecreate_msg(cls, H5E_MINOR, "Oops!")) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_minor;
+ }
+
+ // push a custom error message onto the default stack
+ if (H5Epush2(H5E_DEFAULT, __FILE__, __FUNCTION__, __LINE__, cls, major, minor, "Hello, Error!\n") <
+ 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_push;
+ }
+
+ // print the default error stack
+ if (H5Eprint(H5E_DEFAULT, stderr) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+fail_push:
+ H5Eclose_msg(minor);
+fail_minor:
+ H5Eclose_msg(major);
+fail_major:
+ H5Eunregister_class(cls);
+fail_class:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_count;
+
+ // check the number of error messages on the default stack
+ // and print what's there
+ ssize_t count = H5Eget_num(H5E_DEFAULT);
+ if (count < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_count;
+ }
+ else if (H5Eprint(H5E_DEFAULT, stderr) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+fail_count:;
+ }
+ //!
+
+ //!
+ {
+ // pop 10 error messages off the default error stack
+ // popping off non-existent messages is OK, but might be confusing
+ if (H5Epop(H5E_DEFAULT, 10) < 0)
+ ret_val = EXIT_FAILURE;
+ }
+ //!
+
+ //!
+ {
+ // clear the default error stack (for the current thread)
+ if (H5Eclear2(H5E_DEFAULT) < 0)
+ ret_val = EXIT_FAILURE;
+ }
+ //!
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5G_examples.c b/doxygen/examples/H5G_examples.c
new file mode 100644
index 0000000..3109efb
--- /dev/null
+++ b/doxygen/examples/H5G_examples.c
@@ -0,0 +1,186 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_group, fail_prop, fail_lcpl, fail_file;
+ hid_t file, lcpl, group;
+ char fname[] = "g1.h5";
+ char path[] = "/αυτή/είναι/μια/νέα/ομάδα";
+
+ if ((file = H5Fcreate(fname, H5F_ACC_TRUNC, 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;
+ }
+ // ensure that intermediate groups are created automatically
+ if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // use UTF-8 encoding for link names
+ if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // create five groups
+ if ((group = H5Gcreate(file, path, lcpl, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_group;
+ }
+
+ H5Gclose(group);
+fail_group:
+fail_prop:
+ H5Pclose(lcpl);
+fail_lcpl:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_file;
+ char fname[] = "g1.h5";
+ char path[] = "/αυτή/είναι";
+ hid_t file;
+ H5G_info_t info;
+
+ if ((file = H5Fopen(fname, H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // open one of the intermediate groups
+ if (H5Gget_info_by_name(file, path, &info, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_info;
+ }
+
+ printf("Link count: %llu\n", info.nlinks);
+ switch (info.storage_type) {
+ case H5G_STORAGE_TYPE_COMPACT:
+ printf("Compact storage\n");
+ break;
+ case H5G_STORAGE_TYPE_DENSE:
+ printf("Compact storage\n");
+ break;
+ case H5G_STORAGE_TYPE_SYMBOL_TABLE:
+ printf("Symbol table\n");
+ break;
+ default:
+ printf("UFO\n");
+ break;
+ }
+
+fail_info:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_group, fail_prop, fail_lcpl, fail_file;
+ hid_t file, lcpl, group;
+ char fname[] = "g1.h5";
+ char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα";
+
+ if ((file = H5Fopen(fname, H5F_ACC_RDWR, 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;
+ }
+ // ensure that intermediate groups are created automatically
+ if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // use UTF-8 encoding for link names
+ if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // create an anonymous group
+ if ((group = H5Gcreate_anon(file, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_group;
+ }
+ // link the new group to existing the group at "/αυτή/είναι/μια"
+ if (H5Lcreate_hard(group, ".", file, path, lcpl, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ H5Gclose(group);
+fail_group:
+fail_prop:
+ H5Pclose(lcpl);
+fail_lcpl:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_info, fail_object, fail_file;
+ hid_t file, obj;
+ char fname[] = "g1.h5";
+ char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα";
+ char delete_path[] = "/αυτή/είναι/μια";
+ H5O_info_t info;
+
+ if ((file = H5Fopen(fname, H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // open a "leaf" group as object
+ if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_object;
+ }
+ // delete the link to an intermediate group on the path to the leaf
+ if (H5Ldelete(file, delete_path, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ // link deletion will propagate along hard links along all paths
+ // reachable from the intermediate group and cause reference counts to
+ // be decremented, freeing the objects if the count reaches 0
+ if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_info;
+ }
+
+ printf("Leaf reference count: %d\n", info.rc);
+
+fail_info:
+ H5Oclose(obj);
+fail_object:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5I_examples.c b/doxygen/examples/H5I_examples.c
new file mode 100644
index 0000000..4aa4783
--- /dev/null
+++ b/doxygen/examples/H5I_examples.c
@@ -0,0 +1,242 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_dcpl;
+ hid_t dcpl;
+
+ // create an ID of a pre-defined ID type
+ if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // we can reliably predict the ID type
+ assert(H5Iget_type(dcpl) == H5I_GENPROP_LST);
+ printf("%d\n", H5Iget_type(dcpl));
+
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dcpl;
+ hid_t dcpl;
+
+ // create an ID of a pre-defined ID type
+ if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // this better be valid
+ assert(H5Iis_valid(dcpl) > 0);
+
+ // this ID is NOT associated with any HDF5 file;
+ // see the error message
+ assert(H5Iget_file_id(dcpl) == H5I_INVALID_HID);
+
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_rc, fail_dcpl;
+ hid_t dcpl;
+ int rc;
+
+ // create an ID of a pre-defined ID type
+ if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // retrieve the IDs reference count
+ if ((rc = H5Iget_ref(dcpl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_rc;
+ }
+ printf("Reference count: %d\n", rc);
+
+ // bump its reference count (by 1)
+ if ((rc = H5Iinc_ref(dcpl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_rc;
+ }
+ printf("Reference count: %d\n", rc);
+
+fail_rc:
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_rc, fail_dcpl;
+ hid_t dcpl;
+ int rc;
+
+ // create an ID of a pre-defined ID type
+ if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // decrease its reference count (from 1) to 0
+ if ((rc = H5Idec_ref(dcpl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_rc;
+ }
+ printf("Reference count: %d\n", rc);
+
+ // at this point, the ID is no longer valid
+ assert(H5Iis_valid(dcpl) == 0);
+
+ // dropping the ref. count to 0 has the side-effect of closing
+ // the associated item, and calling H5Pclose would create an error
+ goto fail_dcpl;
+
+fail_rc:
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ herr_t free_func(void *obj)
+ {
+ printf("Calling free_func...\n");
+ H5free_memory(obj);
+ return 0;
+ }
+
+ {
+ __label__ fail_id, fail_obj, fail_register;
+ H5I_type_t type;
+ int * obj;
+ hid_t obj_id;
+
+ // register a new ID type
+ if ((type = H5Iregister_type(128, 1024, &free_func)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_register;
+ }
+ printf("New identifier type ID: %d\n", type);
+
+ // create a new object
+ if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) {
+ ret_val = EXIT_FAILURE;
+ goto fail_obj;
+ }
+
+ // obtain an ID for the new object
+ if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_id;
+ }
+ printf("New object identifier: %ld\n", obj_id);
+
+fail_id:
+ H5Iclear_type(type, 1);
+fail_obj:
+ H5Idestroy_type(type);
+fail_register:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_query, fail_register;
+ H5I_type_t type;
+ hsize_t count;
+
+ // register a new ID type
+ if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_register;
+ }
+ printf("New FOO identifier type ID: %d\n", type);
+
+ // return the number of identifiers of TYPE currently in use
+ if (H5Inmembers(type, &count) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_query;
+ }
+ printf("%llu FOO identifiers in use\n", count);
+
+fail_query:
+ H5Idestroy_type(type);
+fail_register:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_id, fail_register;
+ H5I_type_t type;
+ int obj = 42;
+ hid_t obj_id;
+
+ // register a new ID type
+ if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_register;
+ }
+ printf("New identifier type ID: %d\n", type);
+
+ // obtain an ID for the new object
+ if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_id;
+ }
+ printf("New object identifier: %ld\n", obj_id);
+
+ // bump the reference count
+ assert(H5Iinc_ref(obj_id) == 2);
+
+ // force the deletion of all IDs regardless of reference count
+ H5Iclear_type(type, 1);
+fail_id:
+ H5Idestroy_type(type);
+fail_register:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_register;
+ H5I_type_t type;
+
+ // register a new ID type
+ if ((type = H5Iregister_type(128, 1024, NULL)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_register;
+ }
+ printf("New identifier type ID: %d\n", type);
+
+ // decrementing the identifier type's ref. count to 0 triggers
+ // the type to be destroyed
+ assert(H5Idec_type_ref(type) == 0);
+
+fail_register:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5L_examples.c b/doxygen/examples/H5L_examples.c
new file mode 100644
index 0000000..63f54fe
--- /dev/null
+++ b/doxygen/examples/H5L_examples.c
@@ -0,0 +1,156 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+//!
+herr_t
+iter_cb(hid_t group, const char *name, const H5L_info_t *info, void *op_data)
+{
+ printf("Link \"%s\" is a", name);
+ switch (info->type) {
+ case H5L_TYPE_HARD:
+ printf(" hard link.\n");
+ break;
+ case H5L_TYPE_SOFT:
+ printf(" soft link.\n");
+ break;
+ case H5L_TYPE_EXTERNAL:
+ printf("n external link.\n");
+ break;
+ default:
+ printf(" UFO link.\n");
+ break;
+ }
+
+ return 0;
+}
+//!
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_link, fail_prop, fail_lcpl, fail_create;
+
+ hid_t file, lcpl;
+
+ if ((file = H5Fcreate("l1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_create;
+ }
+
+ // make link creation easier by auto-creating intermediate
+ // groups and UTF-8 encoding of link names
+ if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_lcpl;
+ }
+ if (H5Pset_create_intermediate_group(lcpl, 1) < 0 || H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+
+ // create a loop by hard linking the root group
+ if (H5Lcreate_hard(file, ".", file, "√", lcpl, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_link;
+ }
+ // create a soft link to nowhere
+ if (H5Lcreate_soft("e1 62 80 87 04 09 43 ba 02 d3", file, "/path/to/nowhere", lcpl, H5P_DEFAULT) <
+ 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_link;
+ }
+ // create an external link to nowhere in a non-existent file
+ if (H5Lcreate_external("non-existent-file.h5", "???", file, "external", lcpl, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_link;
+ }
+
+fail_link:
+fail_prop:
+ H5Pclose(lcpl);
+fail_lcpl:
+ H5Fclose(file);
+fail_create:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_iterate, fail_read;
+ hid_t file;
+ hsize_t idx = 0;
+
+ if ((file = H5Fopen("l1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_read;
+ }
+
+ if (H5Literate(file, H5_INDEX_NAME, H5_ITER_NATIVE, &idx, iter_cb, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_iterate;
+ }
+
+fail_iterate:
+ H5Fclose(file);
+fail_read:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_move, fail_update;
+ hid_t file;
+
+ if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_update;
+ }
+
+ // move the "√" link to the group at "/path/to"
+ // the cycle remains!
+ if (H5Lmove(file, "√", file, "path/to/√", H5P_DEFAULT, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_move;
+ }
+
+fail_move:
+ H5Fclose(file);
+fail_update:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_delete, fail_file;
+ hid_t file;
+
+ if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // delete the "external" link
+ if (H5Ldelete(file, "external", H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_delete;
+ }
+
+fail_delete:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5O_examples.c b/doxygen/examples/H5O_examples.c
new file mode 100644
index 0000000..296acd1
--- /dev/null
+++ b/doxygen/examples/H5O_examples.c
@@ -0,0 +1,193 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+
+#define H5P_DEFAULTx2 H5P_DEFAULT, H5P_DEFAULT
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_file;
+ hid_t file, group;
+ char src_path[] = "/a/few/groups";
+
+ if ((file = H5Fcreate("o1.h5", H5F_ACC_TRUNC, H5P_DEFAULTx2)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // create a few groups
+ {
+ __label__ fail_group, fail_lcpl;
+ hid_t lcpl;
+ if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_lcpl;
+ }
+ if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_group;
+ }
+ if ((group = H5Gcreate(file, src_path, lcpl, H5P_DEFAULTx2)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_group;
+ }
+
+ H5Gclose(group);
+fail_group:
+ H5Pclose(lcpl);
+fail_lcpl:;
+ }
+
+ // create a copy
+ if (H5Ocopy(file, ".", file, "copy of", H5P_DEFAULTx2) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_info, fail_file;
+ hid_t file;
+ char path[] = "/a/few/groups";
+ H5O_info2_t info;
+
+ if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // retrieve information about the object
+ if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_info;
+ }
+
+ // determine the object type
+ switch (info.type) {
+ case H5O_TYPE_GROUP:
+ printf("HDF5 group\n");
+ break;
+ case H5O_TYPE_DATASET:
+ printf("HDF5 dataset\n");
+ break;
+ case H5O_TYPE_NAMED_DATATYPE:
+ printf("HDF5 datatype\n");
+ break;
+ default:
+ printf("UFO?\n");
+ break;
+ }
+ // print basic information
+ printf("Reference count: %u\n", info.rc);
+ printf("Attribute count: %lld\n", info.num_attrs);
+
+fail_info:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_obj, fail_incr, fail_file;
+ hid_t file, obj;
+ char path[] = "/a/few/groups";
+ H5O_info2_t info;
+
+ if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // open an object by path name
+ if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_obj;
+ }
+
+ // bump its reference count (by 1)
+ if (H5Oincr_refcount(obj) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_incr;
+ }
+
+ // confirm the new reference count
+ if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_incr;
+ }
+ printf("Reference count: %u\n", info.rc);
+
+fail_incr:
+ H5Oclose(obj);
+fail_obj:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_obj, fail_delete, fail_file;
+ hid_t file, obj;
+ char path[] = "/a/few/groups";
+ H5O_info2_t info;
+
+ if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // open an object by path name
+ if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_obj;
+ }
+
+ // render it inaccessible from the root group by deleting the one and
+ // only link to it; this drops the reference count by 1
+ if (H5Ldelete(file, path, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_delete;
+ }
+
+ // confirm the new reference count
+ if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_delete;
+ }
+ printf("Reference count: %u\n", info.rc);
+
+ // if we close the file at this point, we'd be creating a tombstone,
+ // an object that cannot be reached and that cannot be reclaimed by the
+ // freespace manager; decrement the reference count to zero to prevent that
+ if (H5Idec_ref(obj) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_delete;
+ }
+ else
+ // attempting to close the object would be like a double H5Oclose and fail
+ goto fail_obj;
+
+fail_delete:
+ H5Oclose(obj);
+fail_obj:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5PL_examples.c b/doxygen/examples/H5PL_examples.c
new file mode 100644
index 0000000..e27b432
--- /dev/null
+++ b/doxygen/examples/H5PL_examples.c
@@ -0,0 +1,96 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_set;
+ // enable ONLY filter plugins
+ if (H5PLset_loading_state(H5PL_FILTER_PLUGIN) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_set;
+ }
+
+ // ensure that "/tmp" is at the front of the search path list
+ if (H5PLprepend("/tmp") < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+fail_set:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_read;
+ unsigned size, mask;
+ char buf[255];
+
+ // retrieve the number of entries in the plugin path list
+ if (H5PLsize(&size) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_read;
+ }
+ printf("Number of stored plugin paths: %d\n", size);
+
+ // check the plugin state mask
+ if (H5PLget_loading_state(&mask) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_read;
+ }
+ printf("Filter plugins %s be loaded.\n", (mask & H5PL_FILTER_PLUGIN) == 1 ? "can" : "can't");
+
+ // print the paths in the plugin path list
+ for (unsigned i = 0; i < size; ++i) {
+ if (H5PLget(i, buf, 255) < 0) {
+ ret_val = EXIT_FAILURE;
+ break;
+ }
+ printf("%s\n", buf);
+ }
+
+fail_read:;
+ }
+ //!
+
+ //!
+ {
+ // replace "/tmp" with something more sensible
+ if (H5PLreplace("/foo/bar", 0) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_delete;
+ unsigned size;
+
+ if (H5PLsize(&size) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_delete;
+ }
+
+ // clean out the list of plugin paths
+ for (int i = size - 1; i >= 0; --i) {
+ if (H5PLremove(i) < 0) {
+ ret_val = EXIT_FAILURE;
+ break;
+ }
+ }
+
+fail_delete:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5P_examples.c b/doxygen/examples/H5P_examples.c
new file mode 100644
index 0000000..cdfc03b
--- /dev/null
+++ b/doxygen/examples/H5P_examples.c
@@ -0,0 +1,227 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_dcpl;
+ hid_t dcpl;
+
+ // every property list is created as an instance of a suitable
+ // property list class
+ if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // ...
+
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dcpl, fail_plist_cls_id;
+ hid_t dcpl, plist_cls_id;
+
+ if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+ // to perform introspection on any kind of property list,
+ // we need to determine its property list class by obtaining a handle
+ if ((plist_cls_id = H5Pget_class(dcpl)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_plist_cls_id;
+ }
+ // Compare the handle to the handles of built-in or user-defined
+ // property list classes
+ assert(H5Pequal(plist_cls_id, H5P_DATASET_CREATE) > 0);
+
+fail_plist_cls_id:
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dcpl, fail_prop;
+ hid_t dcpl;
+
+ if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // a property list is updated by adding (or removing) properties
+ if (H5Pset_fill_time(dcpl, H5D_FILL_TIME_NEVER) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+
+fail_prop:
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dcpl;
+ hid_t dcpl;
+
+ if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dcpl;
+ }
+
+ // a property list is "deleted" by closing it
+ H5Pclose(dcpl);
+fail_dcpl:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_cls, fail_prop;
+ hid_t plist_cls, plist;
+ int izero = 0;
+ double dzero = 0.0;
+
+ // create a new property list class
+ if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_cls;
+ }
+ // add a permanent integer property
+ if (H5Pregister2(plist_cls, "int", sizeof(int), &izero, NULL, NULL, NULL, NULL, NULL, NULL, NULL) <
+ 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // add a permanent double property
+ if (H5Pregister2(plist_cls, "double", sizeof(double), &dzero, NULL, NULL, NULL, NULL, NULL, NULL,
+ NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // create an instance of this user-defined property list class
+ if ((plist = H5Pcreate(plist_cls)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+
+ // ...
+
+ H5Pclose(plist);
+fail_prop:
+ H5Pclose_class(plist_cls);
+fail_cls:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_cls, fail_prop, fail_plist;
+ hid_t plist_cls, plist;
+ size_t nprops;
+
+ if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_cls;
+ }
+ if ((plist = H5Pcreate(plist_cls)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_plist;
+ }
+ // count the registered properties of this class
+ if (H5Pget_nprops(plist_cls, &nprops) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_plist;
+ }
+ // this will be 0 as there are no registered properties
+ printf("Property list class has %lu registered properties.\n", nprops);
+
+ // count the properties in this property list
+ if (H5Pget_nprops(plist, &nprops) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_plist;
+ }
+ // will be 1 as there is one temporary property
+ printf("Property list has %lu property.\n", nprops);
+
+fail_plist:
+ H5Pclose(plist);
+fail_prop:
+ H5Pclose_class(plist_cls);
+fail_cls:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_cls, fail_prop, fail_plist;
+ hid_t plist_cls, plist;
+
+ if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_cls;
+ }
+ // create an instance of this user-defined property list class
+ if ((plist = H5Pcreate(plist_cls)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_prop;
+ }
+ // insert a temporary property
+ if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_plist;
+ }
+
+fail_plist:
+ H5Pclose(plist);
+fail_prop:
+ H5Pclose_class(plist_cls);
+fail_cls:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_cls;
+ hid_t plist_cls;
+
+ if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_cls;
+ }
+ // ...
+
+ // a user defined property list class is destroyed by closing the handle
+ H5Pclose_class(plist_cls);
+fail_cls:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5R_examples.c b/doxygen/examples/H5R_examples.c
new file mode 100644
index 0000000..b40b992
--- /dev/null
+++ b/doxygen/examples/H5R_examples.c
@@ -0,0 +1,171 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_file, fail_fspace, fail_dset, fail_sel, fail_aspace, fail_attr, fail_awrite;
+ hid_t file, fspace, dset, aspace, attr;
+ H5R_ref_t ref;
+
+ if ((file = H5Fcreate("reference.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // create a region reference which selects all elements of the dataset at "/data"
+ if ((fspace = H5Screate_simple(2, (hsize_t[]){10, 20}, NULL)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fspace;
+ }
+ if ((dset = H5Dcreate(file, "data", H5T_STD_I32LE, fspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dset;
+ }
+ if (H5Sselect_all(fspace) < 0 || H5Rcreate_region(file, "data", fspace, H5P_DEFAULT, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_sel;
+ }
+ // store the region reference in a scalar attribute of the root group called "region"
+ if ((aspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_aspace;
+ }
+ if ((attr = H5Acreate(file, "region", H5T_STD_REF, aspace, H5P_DEFAULT, H5P_DEFAULT)) ==
+ H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_attr;
+ }
+ if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_awrite;
+ }
+
+fail_awrite:
+ H5Aclose(attr);
+fail_attr:
+ H5Sclose(aspace);
+fail_aspace:
+ H5Rdestroy(&ref);
+fail_sel:
+ H5Dclose(dset);
+fail_dset:
+ H5Sclose(fspace);
+fail_fspace:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_file, fail_attr, fail_aread;
+ hid_t file, attr;
+ H5R_ref_t ref;
+
+ if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // read the dataset region reference from the attribute
+ if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_attr;
+ }
+ if (H5Aread(attr, H5T_STD_REF, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_aread;
+ }
+ assert(H5Rget_type(&ref) == H5R_DATASET_REGION2);
+
+ // get an HDF5 path name for the dataset of the region reference
+ {
+ char buf[255];
+ if (H5Rget_obj_name(&ref, H5P_DEFAULT, buf, 255) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ printf("Object name: \"%s\"\n", buf);
+ }
+
+ H5Rdestroy(&ref);
+fail_aread:
+ H5Aclose(attr);
+fail_attr:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_file, fail_attr, fail_ref;
+ hid_t file, attr;
+ H5R_ref_t ref;
+
+ if ((file = H5Fopen("reference.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // H5T_STD_REF is a generic reference type
+ // we can "update" the attribute value to refer to the attribute itself
+ if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_attr;
+ }
+ if (H5Rcreate_attr(file, "data", "region", H5P_DEFAULT, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_ref;
+ }
+
+ assert(H5Rget_type(&ref) == H5R_ATTR);
+
+ if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ H5Rdestroy(&ref);
+fail_ref:
+ H5Aclose(attr);
+fail_attr:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_file, fail_ref;
+ hid_t file;
+ H5R_ref_t ref;
+
+ // create an HDF5 object reference to the root group
+ if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ if (H5Rcreate_object(file, ".", H5P_DEFAULT, &ref) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_ref;
+ }
+
+ // H5Rdestroy() releases all resources associated with an HDF5 reference
+ H5Rdestroy(&ref);
+fail_ref:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5S_examples.c b/doxygen/examples/H5S_examples.c
new file mode 100644
index 0000000..c542ec0
--- /dev/null
+++ b/doxygen/examples/H5S_examples.c
@@ -0,0 +1,132 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_dspace;
+ hid_t dspace;
+
+ // create a 2D chess board shape (8x8)
+ if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dspace;
+ }
+
+ H5Sclose(dspace);
+fail_dspace:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dspace;
+ hid_t dspace;
+
+ if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dspace;
+ }
+
+ // make changes to the selection on DSPACE
+ // ...
+ // parse the resulting selection
+
+ switch (H5Sget_select_type(dspace)) {
+ case H5S_SEL_HYPERSLABS:
+ // we are dealing with a hyperslab selection
+ // determine the regularity and block structure
+ break;
+ case H5S_SEL_POINTS:
+ // we are dealing with a point selection
+ // for example, retrieve the point list
+ break;
+ case H5S_SEL_ALL:
+ // all dataset elements are selected
+ break;
+ case H5S_SEL_NONE:
+ // the selection is empty
+ break;
+ default:
+ ret_val = EXIT_FAILURE;
+ break;
+ }
+
+ if (dspace != H5S_ALL)
+ H5Sclose(dspace);
+
+fail_dspace:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_select, fail_dspace;
+ hid_t dspace;
+
+ // create a 2D chess board shape (8x8)
+ if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dspace;
+ }
+ // select all black fields: do this w/ a hyperslab union in two steps
+
+ // select the black fields on even rows
+ if (H5Sselect_hyperslab(dspace, H5S_SELECT_SET, (hsize_t[]){0, 0}, (hsize_t[]){2, 2},
+ (hsize_t[]){4, 4}, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_select;
+ }
+ // select the black fields on odd rows
+ // notice the H5S_SELECT_OR operator
+ if (H5Sselect_hyperslab(dspace, H5S_SELECT_OR, (hsize_t[]){1, 1}, (hsize_t[]){2, 2},
+ (hsize_t[]){4, 4}, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_select;
+ }
+
+ // should be 32
+ printf("%lld elements selected.\n", H5Sget_select_npoints(dspace));
+
+fail_select:
+ H5Sclose(dspace);
+fail_dspace:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_select, fail_dspace;
+ hid_t dspace;
+
+ if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dspace;
+ }
+
+ // make changes to and work with the selection on DSPACE
+ // ...
+ // finally, clear the selection
+
+ if (H5Sselect_none(dspace) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_select;
+ }
+
+fail_select:
+ if (dspace != H5S_ALL)
+ H5Sclose(dspace);
+fail_dspace:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5T_examples.c b/doxygen/examples/H5T_examples.c
new file mode 100644
index 0000000..7cfa7d4
--- /dev/null
+++ b/doxygen/examples/H5T_examples.c
@@ -0,0 +1,136 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_insert, fail_dtype, fail_file;
+ hid_t file, dtype;
+
+ if ((file = H5Fcreate("t1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // create a compound datatype with room for real and imaginary parts
+ if ((dtype = H5Tcreate(H5T_COMPOUND, 2 * sizeof(double))) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dtype;
+ }
+ // add the real part now and the imaginary part later
+ if (H5Tinsert(dtype, "re", 0, H5T_IEEE_F64LE) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_insert;
+ }
+ // commit the datatype definition to the file
+ if (H5Tcommit(file, "pre-complex", dtype, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+fail_insert:
+ H5Tclose(dtype);
+fail_dtype:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_dtype, fail_file;
+ hid_t file, dtype;
+
+ if ((file = H5Fopen("t1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // open the datatype object stored in the file
+ if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dtype;
+ }
+
+ switch (H5Tget_class(dtype)) { // this time we are only interested in compounds
+ case H5T_COMPOUND:
+ printf("Record size: %lu bytes\n", H5Tget_size(dtype));
+ printf("Record has %d field(s).\n", H5Tget_nmembers(dtype));
+ break;
+ default:
+ break;
+ }
+
+ H5Tclose(dtype);
+fail_dtype:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_insert, fail_clone, fail_dtype, fail_file;
+ hid_t file, dtype, clone;
+
+ if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // open the datatype object stored in the file
+ if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_dtype;
+ }
+ // the original datatype object is immutable and we need to clone it
+ if ((clone = H5Tcopy(dtype)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_clone;
+ }
+ // remember that the original has enough room for real and imaginary parts
+ // add the imaginary part
+ if (H5Tinsert(clone, "im", sizeof(double), H5T_IEEE_F64LE) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_insert;
+ }
+ // commit the "updated" datatype definition to the file
+ if (H5Tcommit(file, "complex", clone, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+fail_insert:
+ H5Tclose(clone);
+fail_clone:
+ H5Tclose(dtype);
+fail_dtype:
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_file;
+ hid_t file;
+
+ if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ // delete the "pre-complex" datatype by unlinking
+ if (H5Ldelete(file, "pre-complex", H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ H5Fclose(file);
+fail_file:;
+ }
+ //!
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5Z_examples.c b/doxygen/examples/H5Z_examples.c
new file mode 100644
index 0000000..28a1ea2
--- /dev/null
+++ b/doxygen/examples/H5Z_examples.c
@@ -0,0 +1,108 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include
+#include
+#include
+
+//!
+size_t
+filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size,
+ void **buf)
+{
+ buf_size = 0;
+
+ if (flags & H5Z_FLAG_REVERSE) {
+ // read data, e.g., decompress data
+ // ...
+ }
+ else {
+ // write data, e.g., compress data
+ // ...
+ }
+
+ return nbytes;
+}
+//!
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //!
+ {
+ __label__ fail_register;
+ H5Z_class_t cls;
+ cls.version = H5Z_CLASS_T_VERS;
+ cls.id = 256;
+ cls.encoder_present = 1;
+ cls.decoder_present = 1;
+ cls.name = "Identity filter";
+ cls.can_apply = NULL;
+ cls.set_local = NULL;
+ cls.filter = &filter;
+
+ // register the filter
+ if (H5Zregister(&cls) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_register;
+ }
+
+ // do something with filter
+ // ...
+
+ // unregister the filter if no longer required
+ // ...
+
+fail_register:;
+ }
+ //!
+
+ //!
+ {
+ __label__ fail_avail;
+
+ H5Z_filter_t flt = H5Z_FILTER_DEFLATE;
+ unsigned flags = 0;
+
+ // check if the deflate filter is available
+ if (H5Zfilter_avail(flt) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_avail;
+ }
+ // retrieve the deflate filter info
+ if (H5Zget_filter_info(flt, &flags) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_avail;
+ }
+
+ // check if the deflate encoder or decoder is enabled
+ if (H5Z_FILTER_CONFIG_ENCODE_ENABLED & flags)
+ printf("Deflate encoder enabled.\n");
+ if (H5Z_FILTER_CONFIG_DECODE_ENABLED & flags)
+ printf("Deflate decoder enabled.\n");
+
+fail_avail:;
+ }
+ //!
+
+ //!
+ {
+ // N/A
+ } //!
+
+ //!
+ {
+ // unregister the identity filter
+ if (H5Zunregister(256) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //!
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/IOFlow.html b/doxygen/examples/IOFlow.html
new file mode 100644
index 0000000..6b2c27e
--- /dev/null
+++ b/doxygen/examples/IOFlow.html
@@ -0,0 +1,137 @@
+
+
+
+ HDF5 Raw I/O Flow Notes
+
+
+
+
+
+
+
+
+HDF5 Raw I/O Flow Notes
+Quincey Koziol
+ koziol@ncsa.uiuc.edu
+ August 20, 2003
+
+
+
+
+Document's Audience:
+
+
+ - Current H5 library designers and knowledgable external developers.
+
+
+Background Reading:
+
+Introduction:
+
+
+ - What is this document about?
+ - This document attempts to supplement the flow charts describing
+ the flow of control for raw data I/O in the library.
+
+
+
+Figures:
+The following figures provide the main information:
+
+
+Notes From Accompanying Figures:
+
+This section provides notes to augment the information in the accompanying
+ figures.
+
+
+
+ - Validate Parameters - Resolve any H5S_ALL parameters
+ for dataspace selections to actual dataspaces, allocate
+ conversion buffers, etc.
+
+
+ - Space Allocated in File? - Space may not have been allocated
+ in the file to store the dataset data, if "late allocation" was chosen
+ for the allocation time when the dataset was created.
+
+
+ - Allocate & Fill Space - These operations allocate both contiguous
+ and chunked dataset's space in the file. The chunked dataset space
+ allocation iterates through all the chunks in the file and allocates
+ both the B-tree information and the raw data in the file. Because of
+ the way filters work, fill-values are written out for chunked datasets
+ as they are allocated, instead of as a separate step.
+ In parallel
+ I/O, the chunked dataset allocation can potentially be time-consuming,
+ since all the raw data in the dataset is allocated from one process.
+
+
+ - Datatype Conversion Needed? - This currently is the deciding
+ factor between doing "direct I/O" (in serial or parallel) and needing
+ to perform gather/convert/scatter operations. I believe that MPI
+ is capable of performing a limited range of type conversions and if so,
+ we should add support to detect when they can be used. This will
+ allow more I/O operations to be performed collectively.
+
+
+ - Collective I/O Requested/Allowed? - A user has to both request
+ that collective I/O occur and also their I/O operation must meet the
+ requirements that the library sets for supporting collective parallel
+ I/O:
+
+ - The dataspace must be scalar or simple (which is a no-op really,
+ since we don't support "complex" dataspaces in the library
+ currently).
+
+ - The selection must be regular. "all" selections
+ and hyperslab selections that were
+ made with only one call to H5Sselect_hyperslab() (i.e. not a
+ hyperslab selection that has been aggregated over multiple
+ selection calls) are regular. Supporting point and
+ irregular hyperslab selections are on the "to do" list.
+
+ - The dataset must be stored contiguously on disk (as shown in the
+ figure also). Supporting chunked dataset storage is also
+ on the "to do" list.
+
+
+
+
+ - Build "chunk map" - This step still has some scalability issues
+ as it creates a data structure that is proportional to the number of
+ chunks which will be written to, which could potentially be very large.
+ Building the "chunk map" information incrementally is on the "to do"
+ list also.
+
+
+ - Perform Chunked I/O - As the figure shows, there is no support
+ for collective parallel I/O on chunked datasets currently. As noted
+ earlier, this is on the "to do" list.
+
+
+ - Perform "Direct" Serial I/O - "Direct" serial I/O writes data
+ from the application's buffer, without any intervening buffer or memory
+ copies. For maximum efficiency and performance, the elements in the
+ selections should be adjoining.
+
+
+ - Perform Collective Parallel I/O - This step also writes data
+ directly from an application buffer, but additionally uses collective
+ MPI I/O operations to combine the data from each process in the parallel
+ application in an efficient manner.
+
+
+
+
+
+
+
+
diff --git a/doxygen/examples/ThreadSafeLibrary.html b/doxygen/examples/ThreadSafeLibrary.html
index 8daf386..ebb193e 100644
--- a/doxygen/examples/ThreadSafeLibrary.html
+++ b/doxygen/examples/ThreadSafeLibrary.html
@@ -165,7 +165,7 @@ The structure is defined in H5private.h as:
- /* cancelability structure */
+ /* cancellability structure */
typedef struct H5_cancel_struct {
int previous_state;
unsigned int cancel_count;
diff --git a/doxygen/examples/VFL.html b/doxygen/examples/VFL.html
index 9776f96..624d942 100644
--- a/doxygen/examples/VFL.html
+++ b/doxygen/examples/VFL.html
@@ -306,7 +306,7 @@ H5Dread(dataset, type, mspace, fspace, buffer, dxpl);
-The transfer propery list can be queried in a manner similar to the file
+The transfer property 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:
@@ -1210,7 +1210,7 @@ Flush all data for file file to storage.
Example: 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
+extend the Unix file as aggressively 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
diff --git a/doxygen/hdf5_navtree_hacks.js b/doxygen/hdf5_navtree_hacks.js
index 942970c..dda8984 100644
--- a/doxygen/hdf5_navtree_hacks.js
+++ b/doxygen/hdf5_navtree_hacks.js
@@ -223,7 +223,7 @@ $(document).ready(function() {
(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.
+ // this line will trigger 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...
diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml
index 7f71c24..24642b5 100644
--- a/doxygen/hdf5doxy_layout.xml
+++ b/doxygen/hdf5doxy_layout.xml
@@ -7,10 +7,12 @@
-
+
+
+
diff --git a/doxygen/img/HDF5.png b/doxygen/img/HDF5.png
new file mode 100644
index 0000000..0458fa8
Binary files /dev/null and b/doxygen/img/HDF5.png differ
diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h
index 2af9b07..47bb334 100644
--- a/hl/src/H5LTpublic.h
+++ b/hl/src/H5LTpublic.h
@@ -19,7 +19,7 @@
#define H5LT_FILE_IMAGE_DONT_COPY 0x0002 /* The HDF5 lib won't copy */
/* user supplied image buffer. The same image is open with the core driver. */
#define H5LT_FILE_IMAGE_DONT_RELEASE 0x0004 /* The HDF5 lib won't */
-/* deallocate user supplied image buffer. The user application is reponsible */
+/* deallocate user supplied image buffer. The user application is responsible */
/* for doing so. */
#define H5LT_FILE_IMAGE_ALL 0x0007
diff --git a/src/H5ACprivate.h b/src/H5ACprivate.h
index 166ba8d..1fce17e 100644
--- a/src/H5ACprivate.h
+++ b/src/H5ACprivate.h
@@ -91,9 +91,9 @@ typedef enum {
#define H5AC__DEFAULT_MIN_CLEAN_SIZE H5C__DEFAULT_MIN_CLEAN_SIZE
/*
- * Class methods pertaining to caching. Each type of cached object will
+ * Class methods pertaining to caching. Each type of cached object will
* have a constant variable with permanent life-span that describes how
- * to cache the object. That variable will be of type H5AC_class_t and
+ * to cache the object. That variable will be of type H5AC_class_t and
* have the following required fields...
*
* LOAD: Loads an object from disk to memory. The function
@@ -181,7 +181,6 @@ extern H5P_genplist_t *H5AC_ind_dxpl_g;
extern hid_t H5AC_ind_dxpl_id;
/* Default cache configuration. */
-
#define H5AC__DEFAULT_METADATA_WRITE_STRATEGY H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED
/* clang-format off */
diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h
index a7d30ec..5ac4521 100644
--- a/src/H5ACpublic.h
+++ b/src/H5ACpublic.h
@@ -75,7 +75,7 @@ extern "C" {
* field should be used to open a trace file for the cache.
*
*
- * The trace file is a debuging feature that allow the capture of
+ * The trace file is a debugging 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 FALSE, as
* trace file collection imposes considerable overhead.
@@ -120,7 +120,7 @@ extern "C" {
* 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
+ * why it would be desirable. If you can think of one, I'll
* revisit the issue.
*
* set_initial_size: Boolean flag indicating whether the size of the
@@ -393,7 +393,7 @@ extern "C" {
*
* 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
+ * compliance 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.
@@ -573,7 +573,7 @@ typedef struct H5AC_cache_config_t {
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. */
+ * adaptive cache resize code can select as the minimum cache * size. */
long int epoch_length;
/**< Number of cache accesses between runs of the adaptive cache resize
@@ -705,13 +705,13 @@ typedef struct H5AC_cache_config_t {
* 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,
+ * must be consistent 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
+ * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies the 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
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 2bd2686..f6205e8 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -22,6 +22,26 @@
* support partial I/O operations for attributes and they cannot be compressed
* or extended.
*
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5A_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5A_examples.c read
+ * |
+ * | Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5A_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5A_examples.c delete
+ * |
+ *
+ *
+ *
*/
/*
@@ -91,11 +111,11 @@ extern "C" {
*
* \return \herr_t
*
- * \details H5Aclose() terminates access to the attribute specified by
- * \p attr_id by releasing the identifier.
+ * \details H5Aclose() terminates access to the attribute through
+ * \p attr_id and releases the identifier.
*
- * \attention Further use of a released attribute identifier is illegal; a
- * function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5A_examples.c create
*
* \since 1.0.0
*
@@ -123,27 +143,19 @@ H5_DLL herr_t H5Aclose(hid_t attr_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.
+ * \p type_id and \p space_id.
*
- * The access property list is currently unused, but will be used in
- * the future. This property list should currently be #H5P_DEFAULT.
+ * \plist_unused{acpl}
*
* 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.
*
+ * \par Example
+ * \snippet H5A_examples.c create
+ *
* \since 1.8.0
*
* \see H5Aclose()
@@ -173,28 +185,19 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_
* 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).
+ * name relative to \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.
+ * dataspace, \p type_id and \p space_id.
*
- * 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.
+ * \plist_unused{aapl}
*
* 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
*
*/
@@ -213,10 +216,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a
*
* \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.
+ *
+ * \attention This function should not be used when other attribute identifiers
+ * are open on \p loc_id. This may cause the internal indexes of
+ * the attributes to change and future writes to the open
+ * attributes to produce incorrect results.
+ *
+ * \par Example
+ * \snippet H5A_examples.c delete
*
* \since 1.0.0
*
@@ -243,27 +250,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name);
*
* 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).
+ * \p obj_name, respectively.
*
* 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,
+ * index, \p n. The type of index is specified by \p idx_type.
+ * The order in which the index is to be traversed is specified by
+ * \p 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
+ * respectively, the fifth attribute in lexicographic 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.
@@ -291,9 +287,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id
* 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.
@@ -342,9 +335,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
* \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).
+ * or an absolute name, based in the root group of the file.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -368,9 +359,6 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *
* 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
*
*/
@@ -387,32 +375,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
* \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 with an attribute identifier, \p attr_id. 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
*
*/
@@ -440,16 +405,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
* 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().
+ * \p order and \p n, respectively.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -467,8 +425,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* \brief Retrieves attribute information, by attribute name
*
* \fgdt_loc_id
- *
- * \param[in] obj_name Name of object to which attribute is attached,
+ * \param[in] obj_name Name of the object to which an attribute is attached,
* relative to location
* \param[in] attr_name Attribute name
* \param[out] ainfo Struct containing returned attribute information
@@ -481,11 +438,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* 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.
@@ -516,8 +468,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char
* 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
+ * If the user only wants to retrieve the name length, the
+ * values 0 and NULL should be passed for the parameters
* \p bufsize and \p buf.
*
* \since 1.0.0
@@ -528,7 +480,7 @@ 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
+ * \brief Gets an attribute name by attribute index position
*
* \fgdt_loc_id
* \param[in] obj_name Name of object to which attribute is attached,
@@ -549,13 +501,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
* 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().
+ * \p order and \p n, respectively.
*
* 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
@@ -595,7 +543,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Returns the amount of storage required for an attribute
+ * \brief Returns the amount of storage used to store an attribute
*
* \attr_id
*
@@ -613,17 +561,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Gets an attribute datatype
+ * \brief Gets an attribute's datatype
*
* \attr_id
*
* \return \hid_t{datatype}
*
- * \details H5Aget_type() retrieves a copy of the datatype for an attribute.
+ * \details H5Aget_type() retrieves a copy of the attribute's datatype.
* 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.
+ * are always read-only.
*
* The datatype identifier returned from this function must be
* released with H5Tclose() or resource leaks will develop.
@@ -636,7 +583,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Calls user-defined function for each attribute on an object
+ * \brief Calls a user-defined function for each attribute on an object
*
* \fgdt_loc_id
* \param[in] idx_type Type of index
@@ -663,24 +610,13 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* 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
+ * alphanumeric 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.
*
@@ -690,11 +626,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* 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
@@ -730,31 +661,17 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* 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
+ * alphanumeric 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.
*
@@ -764,25 +681,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* 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.
@@ -809,8 +707,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* \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.
+ * \plist_unused{aapl_id}
*
* This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
* before the attribute can be accessed for any further purpose,
@@ -819,6 +716,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* The attribute identifier returned by this function must be released
* with H5Aclose() or resource leaks will develop.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \since 1.8.0
*
* \see H5Aclose(), H5Acreate()
@@ -843,17 +743,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
*
* \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).
+ * \p obj_name, respectively.
*
* 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().
+ * \p n, respectively.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -892,11 +788,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t
*
* \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).
+ * \p loc_id.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -933,6 +827,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att
* Datatype conversion takes place at the time of a read or write and
* is automatic.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \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.
@@ -980,15 +877,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name
* 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.
*
+ * \par Example
+ * \snippet H5A_examples.c update
+ *
* \version 1.8.8 Fortran updated to Fortran2003.
* \version 1.4.2 Fortran \p dims parameter added in this release
* \since 1.0.0
@@ -1070,9 +964,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
*
* \return \hid_tv{attribute}
*
- * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ * \deprecation_note{H5Acreate2()}
*
- * \deprecated Deprecated in favor of H5Acreate2()
+ * \plist_unused{acpl}
*
* \details H5Acreate1() creates an attribute, \p name, which is attached
* to the object specified by the identifier \p loc_id.
@@ -1080,18 +974,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
* 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.
+ * \p type_id and \p space_id.
*
* \since 1.8.0
*
@@ -1113,8 +996,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
* \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().
+ * \deprecation_note{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.
@@ -1137,8 +1019,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
*
* \return \herr_t
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aiterate2().
+ * \deprecation_note{H5Aiterate2()}
*
* \details H5Aiterate1() iterates over the attributes of the object
* specified by its identifier, \p loc_id. The object can be a
@@ -1150,10 +1031,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
* \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
@@ -1171,8 +1048,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_idx().
+ * \deprecation_note{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
@@ -1198,8 +1074,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_name().
+ * \deprecation_note{H5Aopen_by_name()}
*
* \details H5Aopen_name() opens an attribute specified by its name,
* \p name, which is attached to the object specified with
diff --git a/src/H5B2private.h b/src/H5B2private.h
index de823e4..1a7d0c8 100644
--- a/src/H5B2private.h
+++ b/src/H5B2private.h
@@ -29,7 +29,7 @@
#include "H5B2public.h"
/* Private headers needed by this file */
-#include "H5Fprivate.h" /* File access */
+#include "H5Fprivate.h" /* File access */
/**************************/
/* Library Private Macros */
diff --git a/src/H5Cpkg.h b/src/H5Cpkg.h
index 69ac9b1..ac1d018 100644
--- a/src/H5Cpkg.h
+++ b/src/H5Cpkg.h
@@ -1030,11 +1030,11 @@ struct H5C_t
*
* from the H5C__DLL_PRE_REMOVE_SC macro. With the addition of the
* epoch markers used in the age out based cache size reduction algorithm,
- * this invarient need not hold, as the epoch markers are of size 0.
+ * this invariant need not hold, as the epoch markers are of size 0.
*
* One could argue that I should have given the epoch markers a positive
* size, but this would break the index_size = LRU_list_size + pl_size
- * + pel_size invarient.
+ * + pel_size invariant.
*
* Alternatively, I could pass the current decr_mode in to the macro,
* and just skip the check whenever epoch markers may be in use.
@@ -1419,23 +1419,6 @@ if ( ( (entry_ptr) == NULL ) || \
* H5C__UPDATE_CACHE_HIT_RATE_STATS(), which is always active as
* the cache hit rate stats are always collected and available.
*
- * Changes:
- *
- * JRM -- 3/21/06
- * Added / updated macros for pinned entry related stats.
- *
- * JRM -- 8/9/06
- * More pinned entry stats related updates.
- *
- * JRM -- 3/31/07
- * Updated H5C__UPDATE_STATS_FOR_PROTECT() to keep stats on
- * read and write protects.
- *
- * MAM -- 1/15/09
- * Created H5C__UPDATE_MAX_INDEX_SIZE_STATS to contain
- * common code within macros that update the maximum
- * index, clean_index, and dirty_index statistics fields.
- *
***********************************************************************/
#define H5C__UPDATE_CACHE_HIT_RATE_STATS(cache_ptr, hit) \
@@ -2218,8 +2201,8 @@ if ( (cache_ptr)->index_size != \
* Function: H5C__REMOVE_ENTRY_FROM_SLIST
*
* Purpose: Remove the specified instance of H5C_cache_entry_t from the
- * index skip list in the specified instance of H5C_t. Update
- * the associated length and size fields.
+ * index skip list in the specified instance of H5C_t. Update
+ * the associated length and size fields.
*
* Return: N/A
*
@@ -2227,20 +2210,20 @@ if ( (cache_ptr)->index_size != \
*
* Modifications:
*
- * JRM -- 7/21/04
- * Updated function for the addition of the hash table.
+ * JRM -- 7/21/04
+ * Updated function for the addition of the hash table.
*
- * JRM - 7/27/04
- * Converted from the function H5C_remove_entry_from_tree()
- * to the macro H5C__REMOVE_ENTRY_FROM_TREE in the hopes of
- * wringing a little more performance out of the cache.
+ * JRM - 7/27/04
+ * Converted from the function H5C_remove_entry_from_tree()
+ * to the macro H5C__REMOVE_ENTRY_FROM_TREE in the hopes of
+ * wringing a little more performance out of the cache.
*
- * QAK -- 11/27/04
- * Switched over to using skip list routines.
+ * QAK -- 11/27/04
+ * Switched over to using skip list routines.
*
- * JRM -- 3/28/07
- * Updated sanity checks for the new is_read_only and
- * ro_ref_count fields in H5C_cache_entry_t.
+ * JRM -- 3/28/07
+ * Updated sanity checks for the new is_read_only and
+ * ro_ref_count fields in H5C_cache_entry_t.
*
*-------------------------------------------------------------------------
*/
@@ -2276,7 +2259,7 @@ if ( (cache_ptr)->index_size != \
* Function: H5C__UPDATE_SLIST_FOR_SIZE_CHANGE
*
* Purpose: Update cache_ptr->slist_size for a change in the size of
- * and entry in the slist.
+ * and entry in the slist.
*
* Return: N/A
*
@@ -2284,15 +2267,15 @@ if ( (cache_ptr)->index_size != \
*
* Modifications:
*
- * JRM -- 8/27/06
- * Added the H5C_DO_SANITY_CHECKS version of the macro.
+ * JRM -- 8/27/06
+ * Added the H5C_DO_SANITY_CHECKS version of the macro.
*
- * This version maintains the slist_size_increase field
- * that are used in sanity checks in the flush routines.
+ * This version maintains the slist_size_increase field
+ * that are used in sanity checks in the flush routines.
*
- * All this is needed as the fractal heap needs to be
- * able to dirty, resize and/or move entries during the
- * flush.
+ * All this is needed as the fractal heap needs to be
+ * able to dirty, resize and/or move entries during the
+ * flush.
*
*-------------------------------------------------------------------------
*/
@@ -2405,16 +2388,16 @@ if ( (cache_ptr)->index_size != \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the head.\
- */ \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* Use the dirty flag to infer whether the entry is on the clean or \
@@ -2468,16 +2451,16 @@ if ( (cache_ptr)->index_size != \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the head \
- */ \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* End modified LRU specific code. */ \
@@ -2660,28 +2643,28 @@ if ( (cache_ptr)->index_size != \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the \
- * head. \
- */ \
+ * head. \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* since the entry is being flushed or cleared, one would think \
- * that it must be dirty -- but that need not be the case. Use the \
- * dirty flag to infer whether the entry is on the clean or dirty \
- * LRU list, and remove it. Then insert it at the head of the \
- * clean LRU list. \
+ * that it must be dirty -- but that need not be the case. Use the \
+ * dirty flag to infer whether the entry is on the clean or dirty \
+ * LRU list, and remove it. Then insert it at the head of the \
+ * clean LRU list. \
* \
* The function presumes that a dirty entry will be either cleared \
- * or flushed shortly, so it is OK if we put a dirty entry on the \
- * clean LRU list. \
+ * or flushed shortly, so it is OK if we put a dirty entry on the \
+ * clean LRU list. \
*/ \
\
if ( (entry_ptr)->is_dirty ) { \
@@ -2722,17 +2705,17 @@ if ( (cache_ptr)->index_size != \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the \
- * head. \
- */ \
+ * head. \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* End modified LRU specific code. */ \
@@ -2816,7 +2799,7 @@ if ( (cache_ptr)->index_size != \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* insert the entry at the head of the clean or dirty LRU list as \
@@ -2857,7 +2840,7 @@ if ( (cache_ptr)->index_size != \
(cache_ptr)->pel_tail_ptr, \
(cache_ptr)->pel_len, \
(cache_ptr)->pel_size, (fail_val)) \
- \
+ \
} else { \
\
/* modified LRU specific code */ \
@@ -2866,7 +2849,7 @@ if ( (cache_ptr)->index_size != \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* End modified LRU specific code. */ \
@@ -2935,12 +2918,12 @@ if ( (cache_ptr)->index_size != \
HDassert( !((entry_ptr)->is_read_only) ); \
HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \
HDassert( (entry_ptr)->size > 0 ); \
- \
+ \
if ( (entry_ptr)->is_pinned ) { \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \
- (cache_ptr)->pel_tail_ptr, \
- (cache_ptr)->pel_len, \
+ (cache_ptr)->pel_tail_ptr, \
+ (cache_ptr)->pel_len, \
(cache_ptr)->pel_size, (fail_val)) \
HDassert( (cache_ptr)->pel_len >= 0 ); \
\
@@ -2952,7 +2935,7 @@ if ( (cache_ptr)->index_size != \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* Similarly, remove the entry from the clean or dirty LRU list \
@@ -2998,12 +2981,12 @@ if ( (cache_ptr)->index_size != \
HDassert( !((entry_ptr)->is_read_only) ); \
HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \
HDassert( (entry_ptr)->size > 0 ); \
- \
+ \
if ( (entry_ptr)->is_pinned ) { \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \
- (cache_ptr)->pel_tail_ptr, \
- (cache_ptr)->pel_len, \
+ (cache_ptr)->pel_tail_ptr, \
+ (cache_ptr)->pel_len, \
(cache_ptr)->pel_size, (fail_val)) \
HDassert( (cache_ptr)->pel_len >= 0 ); \
\
@@ -3015,7 +2998,7 @@ if ( (cache_ptr)->index_size != \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* End modified LRU specific code. */ \
@@ -3066,20 +3049,20 @@ if ( (cache_ptr)->index_size != \
HDassert( (entry_ptr)->size > 0 ); \
\
if ( ! ( (entry_ptr)->is_pinned ) ) { \
- \
+ \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the head. \
- */ \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* remove the entry from either the clean or dirty LUR list as \
@@ -3088,7 +3071,7 @@ if ( (cache_ptr)->index_size != \
if ( was_dirty ) { \
\
H5C__AUX_DLL_REMOVE((entry_ptr), \
- (cache_ptr)->dLRU_head_ptr, \
+ (cache_ptr)->dLRU_head_ptr, \
(cache_ptr)->dLRU_tail_ptr, \
(cache_ptr)->dLRU_list_len, \
(cache_ptr)->dLRU_list_size, \
@@ -3097,34 +3080,34 @@ if ( (cache_ptr)->index_size != \
} else { \
\
H5C__AUX_DLL_REMOVE((entry_ptr), \
- (cache_ptr)->cLRU_head_ptr, \
+ (cache_ptr)->cLRU_head_ptr, \
(cache_ptr)->cLRU_tail_ptr, \
(cache_ptr)->cLRU_list_len, \
(cache_ptr)->cLRU_list_size, \
- (fail_val)) \
+ (fail_val)) \
} \
\
/* insert the entry at the head of either the clean or dirty \
- * LRU list as appropriate. \
+ * LRU list as appropriate. \
*/ \
\
if ( (entry_ptr)->is_dirty ) { \
\
H5C__AUX_DLL_PREPEND((entry_ptr), \
- (cache_ptr)->dLRU_head_ptr, \
+ (cache_ptr)->dLRU_head_ptr, \
(cache_ptr)->dLRU_tail_ptr, \
(cache_ptr)->dLRU_list_len, \
(cache_ptr)->dLRU_list_size, \
- (fail_val)) \
+ (fail_val)) \
\
} else { \
\
H5C__AUX_DLL_PREPEND((entry_ptr), \
- (cache_ptr)->cLRU_head_ptr, \
+ (cache_ptr)->cLRU_head_ptr, \
(cache_ptr)->cLRU_tail_ptr, \
(cache_ptr)->cLRU_list_len, \
(cache_ptr)->cLRU_list_size, \
- (fail_val)) \
+ (fail_val)) \
} \
\
/* End modified LRU specific code. */ \
@@ -3144,20 +3127,20 @@ if ( (cache_ptr)->index_size != \
HDassert( (entry_ptr)->size > 0 ); \
\
if ( ! ( (entry_ptr)->is_pinned ) ) { \
- \
+ \
/* modified LRU specific code */ \
\
/* remove the entry from the LRU list, and re-insert it at the head. \
- */ \
+ */ \
\
H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
(cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_len, \
(cache_ptr)->LRU_list_size, (fail_val)) \
\
/* End modified LRU specific code. */ \
@@ -3211,43 +3194,43 @@ if ( (cache_ptr)->index_size != \
HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \
HDassert( (entry_ptr)->size > 0 ); \
HDassert( new_size > 0 ); \
- \
+ \
if ( (entry_ptr)->is_pinned ) { \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \
- (cache_ptr)->pel_size, \
- (entry_ptr)->size, \
- (new_size)); \
- \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \
+ (cache_ptr)->pel_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
+ \
} else { \
\
/* modified LRU specific code */ \
\
- /* Update the size of the LRU list */ \
+ /* Update the size of the LRU list */ \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \
- (cache_ptr)->LRU_list_size, \
- (entry_ptr)->size, \
- (new_size)); \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
\
/* Similarly, update the size of the clean or dirty LRU list as \
- * appropriate. At present, the entry must be clean, but that \
- * could change. \
+ * appropriate. At present, the entry must be clean, but that \
+ * could change. \
*/ \
\
if ( (entry_ptr)->is_dirty ) { \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \
- (cache_ptr)->dLRU_list_size, \
- (entry_ptr)->size, \
- (new_size)); \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \
+ (cache_ptr)->dLRU_list_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
\
} else { \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \
- (cache_ptr)->cLRU_list_size, \
- (entry_ptr)->size, \
- (new_size)); \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \
+ (cache_ptr)->cLRU_list_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
} \
\
/* End modified LRU specific code. */ \
@@ -3270,21 +3253,21 @@ if ( (cache_ptr)->index_size != \
\
if ( (entry_ptr)->is_pinned ) { \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \
- (cache_ptr)->pel_size, \
- (entry_ptr)->size, \
- (new_size)); \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \
+ (cache_ptr)->pel_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
\
} else { \
\
/* modified LRU specific code */ \
\
- /* Update the size of the LRU list */ \
+ /* Update the size of the LRU list */ \
\
- H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \
- (cache_ptr)->LRU_list_size, \
- (entry_ptr)->size, \
- (new_size)); \
+ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_size, \
+ (entry_ptr)->size, \
+ (new_size)); \
\
/* End modified LRU specific code. */ \
} \
@@ -3344,39 +3327,39 @@ if ( (cache_ptr)->index_size != \
(cache_ptr)->pel_size, (fail_val)) \
HDassert( (cache_ptr)->pel_len >= 0 ); \
\
- /* modified LRU specific code */ \
+ /* modified LRU specific code */ \
\
- /* insert the entry at the head of the LRU list. */ \
+ /* insert the entry at the head of the LRU list. */ \
\
- H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
- (cache_ptr)->LRU_tail_ptr, \
- (cache_ptr)->LRU_list_len, \
- (cache_ptr)->LRU_list_size, (fail_val)) \
+ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \
+ (cache_ptr)->LRU_tail_ptr, \
+ (cache_ptr)->LRU_list_len, \
+ (cache_ptr)->LRU_list_size, (fail_val)) \
\
- /* Similarly, insert the entry at the head of either the clean \
- * or dirty LRU list as appropriate. \
- */ \
+ /* Similarly, insert the entry at the head of either the clean \
+ * or dirty LRU list as appropriate. \
+ */ \
\
- if ( (entry_ptr)->is_dirty ) { \
+ if ( (entry_ptr)->is_dirty ) { \
\
- H5C__AUX_DLL_PREPEND((entry_ptr), \
- (cache_ptr)->dLRU_head_ptr, \
- (cache_ptr)->dLRU_tail_ptr, \
- (cache_ptr)->dLRU_list_len, \
- (cache_ptr)->dLRU_list_size, \
- (fail_val)) \
+ H5C__AUX_DLL_PREPEND((entry_ptr), \
+ (cache_ptr)->dLRU_head_ptr, \
+ (cache_ptr)->dLRU_tail_ptr, \
+ (cache_ptr)->dLRU_list_len, \
+ (cache_ptr)->dLRU_list_size, \
+ (fail_val)) \
\
- } else { \
+ } else { \
\
- H5C__AUX_DLL_PREPEND((entry_ptr), \
- (cache_ptr)->cLRU_head_ptr, \
- (cache_ptr)->cLRU_tail_ptr, \
- (cache_ptr)->cLRU_list_len, \
- (cache_ptr)->cLRU_list_size, \
- (fail_val)) \
- } \
+ H5C__AUX_DLL_PREPEND((entry_ptr), \
+ (cache_ptr)->cLRU_head_ptr, \
+ (cache_ptr)->cLRU_tail_ptr, \
+ (cache_ptr)->cLRU_list_len, \
+ (cache_ptr)->cLRU_list_size, \
+ (fail_val)) \
+ } \
\
- /* End modified LRU specific code. */ \
+ /* End modified LRU specific code. */ \
\
} /* H5C__UPDATE_RP_FOR_UNPIN */
diff --git a/src/H5Cprivate.h b/src/H5Cprivate.h
index ce03ba0..d7a1949 100644
--- a/src/H5Cprivate.h
+++ b/src/H5Cprivate.h
@@ -44,7 +44,8 @@
#define H5C_MAX_ENTRY_SIZE ((size_t)(32 * 1024 * 1024))
/* H5C_COLLECT_CACHE_STATS controls overall collection of statistics
- * on cache activity. In general, this #define should be set to 0.
+ * on cache activity. In general, this #define should be set to 1 in
+ * debug mode, and 0 in production mode..
*/
#define H5C_COLLECT_CACHE_STATS 0
diff --git a/src/H5Dpkg.h b/src/H5Dpkg.h
index 31c0bd1..04e02e9 100644
--- a/src/H5Dpkg.h
+++ b/src/H5Dpkg.h
@@ -78,17 +78,17 @@ typedef struct H5D_type_info_t {
hid_t dst_type_id; /* Destination datatype ID */
/* Computed/derived values */
- size_t src_type_size; /* Size of source type */
- size_t dst_type_size; /* Size of destination type*/
+ size_t src_type_size; /* Size of source type */
+ size_t dst_type_size; /* Size of destination type */
size_t max_type_size; /* Size of largest source/destination type */
hbool_t is_conv_noop; /* Whether the type conversion is a NOOP */
hbool_t is_xform_noop; /* Whether the data transform is a NOOP */
const H5T_subset_info_t *cmpd_subset; /* Info related to the compound subset conversion functions */
H5T_bkg_t need_bkg; /* Type of background buf needed */
- size_t request_nelmts; /* Requested strip mine */
- uint8_t * tconv_buf; /* Datatype conv buffer */
+ size_t request_nelmts; /* Requested strip mine */
+ uint8_t * tconv_buf; /* Datatype conv buffer */
hbool_t tconv_buf_allocated; /* Whether the type conversion buffer was allocated */
- uint8_t * bkg_buf; /* Background buffer */
+ uint8_t * bkg_buf; /* Background buffer */
hbool_t bkg_buf_allocated; /* Whether the background buffer was allocated */
} H5D_type_info_t;
@@ -385,7 +385,7 @@ typedef struct H5D_rdcc_t {
struct H5D_rdcc_ent_t * head; /* Head of doubly linked list */
struct H5D_rdcc_ent_t * tail; /* Tail of doubly linked list */
size_t nbytes_used; /* Current cached raw data in bytes */
- int nused; /* Number of chunk slots in use */
+ int nused; /* Number of chunk slots in use */
H5D_chunk_cached_t last; /* Cached copy of last chunk information */
struct H5D_rdcc_ent_t **slot; /* Chunk slots, each points to a chunk*/
H5SL_t * sel_chunks; /* Skip list containing information for each chunk selected */
@@ -404,7 +404,7 @@ typedef struct H5D_rdcdc_t {
/*
* A dataset is made of two layers, an H5D_t struct that is unique to
- * each instance of an opened datset, and a shared struct that is only
+ * each instance of an opened dataset, and a shared struct that is only
* created once for a given dataset. Thus, if a dataset is opened twice,
* there will be two IDs and two H5D_t structs, both sharing one H5D_shared_t.
*/
diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index 5170f67..ed4fbc1 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -11,6 +11,12 @@
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/*
+ * This file contains public declarations for the H5D module.
+ */
+#ifndef H5Dpublic_H
+#define H5Dpublic_H
+
/**\defgroup H5D H5D
*
* Use the functions in this module to manage HDF5 datasets, including the
@@ -19,14 +25,31 @@
* name or by a handle. Such handles can be obtained by either creating or
* opening the dataset.
*
+ * Typical stages in the HDF5 dataset life cycle are shown below in introductory
+ * examples.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5D_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5D_examples.c read
+ * |
+ * | Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5D_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5D_examples.c delete
+ * |
+ *
+ *
+ *
*/
-/*
- * This file contains public declarations for the H5D module.
- */
-#ifndef H5Dpublic_H
-#define H5Dpublic_H
-
/* System headers needed by this file */
/* Public headers needed by this file */
@@ -62,12 +85,11 @@
* 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_LAYOUT_ERROR = -1, /**< error */
+ H5D_COMPACT = 0, /**< raw data is small (< 64KB) */
+ H5D_CONTIGUOUS = 1, /**< contiguous layout */
+ H5D_CHUNKED = 2, /**< chunked or tiled layout */
+ H5D_NLAYOUTS = 3 /**< this one must be last! */
} H5D_layout_t;
//!
@@ -85,11 +107,11 @@ typedef enum H5D_chunk_index_t {
* Values for the space allocation time property
*/
typedef enum H5D_alloc_time_t {
- H5D_ALLOC_TIME_ERROR = -1,
- H5D_ALLOC_TIME_DEFAULT = 0,
- H5D_ALLOC_TIME_EARLY = 1,
- H5D_ALLOC_TIME_LATE = 2,
- H5D_ALLOC_TIME_INCR = 3
+ H5D_ALLOC_TIME_ERROR = -1, /**< Error */
+ H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */
+ H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */
+ H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */
+ H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */
} H5D_alloc_time_t;
//!
@@ -98,10 +120,11 @@ typedef enum H5D_alloc_time_t {
* 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_ERROR = -1, /**< Error */
+ H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */
+ H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been partially allocated for this dataset.
+ (Used only for datasets with chunked storage.) */
+ H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been allocated for this dataset. */
} H5D_space_status_t;
//!
@@ -110,10 +133,10 @@ typedef enum H5D_space_status_t {
* 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_ERROR = -1, /**< Error */
+ H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */
+ H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */
+ H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */
} H5D_fill_time_t;
//!
@@ -122,10 +145,10 @@ typedef enum H5D_fill_time_t {
* 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_ERROR = -1, /**< Error */
+ H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */
+ H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */
+ H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */
} H5D_fill_value_t;
//!
@@ -223,7 +246,7 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us
* \brief Creates a new dataset and links it into the file
*
* \fgdta_loc_id
- * \param[in] name Name of the dataset to create
+ * \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \lcpl_id
@@ -248,13 +271,6 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us
* \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
@@ -262,19 +278,19 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us
*
* 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.
+ * 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
+ * read from or written to. Reading data from a dataset 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.
+ * \par Example
+ * \snippet H5D_examples.c create
*
* \since 1.8.0
*
@@ -313,34 +329,14 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
* 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.
+ * when the file is closed.
*
* \since 1.8.0
*
- * \see H5Olink(), H5Dcreate(), Using Identifiers
+ * \see H5Olink(), H5Dcreate()
*
*/
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);
@@ -366,12 +362,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d
* 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()
@@ -397,6 +387,9 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
* be released with H5Sclose() when the identifier is no longer
* needed so that resource leaks will not occur.
*
+ * \par Example
+ * \snippet H5D_examples.c update
+ *
* \see H5Sclose()
*
*/
@@ -405,7 +398,19 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
- * \todo Document this function!
+ *
+ * \brief Determines whether space has been allocated for a dataset
+ *
+ * \dset_id
+ * \param[out] allocation Space allocation status
+ *
+ * \return \herr_t
+ *
+ * \details H5Dget_space_status() determines whether space has been allocated
+ * for the dataset \p dset_id.
+ *
+ * \since 1.6.0
+ *
*/
H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
@@ -424,27 +429,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
*
* 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.
+ * is read-only.
*
*/
H5_DLL hid_t H5Dget_type(hid_t dset_id);
@@ -464,9 +449,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id);
* 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);
@@ -500,10 +482,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
* 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
*
*/
@@ -522,11 +500,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
* \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.
- *
+ * H5Dget_storage_size() reports only the space required to store
+ * the dataset elements, excluding any metadata.
* \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
@@ -536,21 +511,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
* 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.
+ * \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 dataset
+ * element. H5Sget_simple_extent_npoints() and H5Tget_size()
+ * can be used to calculate that amount.
*
- * \attention H5Dget_storage_size() does not differentiate between 0 (zero),
+ * \warning 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);
@@ -588,7 +561,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs
*
* \dset_id
*
- * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF,
+ * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
* a negative value.
*
* \details H5Dget_offset() returns the address in the file of
@@ -637,9 +610,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
* 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 number of elements selected in the memory dataspace \Emph{must}
+ * be equal to the number of elements selected in the file dataspace.
*
* The behavior of the library for the various combinations of
* valid dataspace identifiers and #H5S_ALL for the \p mem_space_id
@@ -684,14 +656,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
* |
* 
+ 
