summaryrefslogtreecommitdiffstats
path: root/doxygen/examples
diff options
context:
space:
mode:
Diffstat (limited to 'doxygen/examples')
-rw-r--r--doxygen/examples/H5D_examples.c81
-rw-r--r--doxygen/examples/H5E_examples.c97
-rw-r--r--doxygen/examples/H5F_examples.c55
-rw-r--r--doxygen/examples/H5G_examples.c186
-rw-r--r--doxygen/examples/H5I_examples.c242
-rw-r--r--doxygen/examples/H5L_examples.c156
-rw-r--r--doxygen/examples/H5O_examples.c193
-rw-r--r--doxygen/examples/H5PL_examples.c97
-rw-r--r--doxygen/examples/H5P_examples.c227
-rw-r--r--doxygen/examples/H5R_examples.c171
-rw-r--r--doxygen/examples/H5S_examples.c132
-rw-r--r--doxygen/examples/H5T_examples.c136
-rw-r--r--doxygen/examples/H5Z_examples.c108
-rw-r--r--doxygen/examples/H5_examples.c85
14 files changed, 1958 insertions, 8 deletions
diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c
index aad057d..4e54c1d 100644
--- a/doxygen/examples/H5D_examples.c
+++ b/doxygen/examples/H5D_examples.c
@@ -5,6 +5,86 @@
#include <stdio.h>
#include <stdlib.h>
+//! <!-- [H5Dchunk_iter_cb] -->
+int
+chunk_cb(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data)
+{
+ // only print the allocated chunk size only
+ printf("%d\n", nbytes);
+ return EXIT_SUCCESS;
+}
+//! <!-- [H5Dchunk_iter_cb] -->
+
+//! <!-- [H5Ovisit_cb] -->
+herr_t
+H5Ovisit_cb(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data)
+{
+ herr_t retval = 0;
+ char * base_path = (char *)op_data;
+
+ if (info->type == H5O_TYPE_DATASET) // current object is a dataset
+ {
+ hid_t dset, dcpl;
+ if ((dset = H5Dopen(obj, name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ retval = -1;
+ goto func_leave;
+ }
+ if ((dcpl = H5Dget_create_plist(dset)) == H5I_INVALID_HID) {
+ retval = -1;
+ goto fail_dcpl;
+ }
+ if (H5Pget_layout(dcpl) == H5D_CHUNKED) // dataset is chunked
+ {
+ __label__ fail_dtype, fail_dspace, fail_shape;
+ hid_t dspace, dtype;
+ size_t size, i;
+ int rank;
+ hsize_t cdims[H5S_MAX_RANK];
+
+ // get resources
+ if ((dtype = H5Dget_type(dset)) < 0) {
+ retval = -1;
+ goto fail_dtype;
+ }
+ if ((dspace = H5Dget_space(dset)) < 0) {
+ retval = -1;
+ goto fail_dspace;
+ }
+ // get the shape
+ if ((size = H5Tget_size(dtype)) == 0 || (rank = H5Sget_simple_extent_ndims(dspace)) < 0 ||
+ H5Pget_chunk(dcpl, H5S_MAX_RANK, cdims) < 0) {
+ retval = -1;
+ goto fail_shape;
+ }
+ // calculate the nominal chunk size
+ size = 1;
+ for (i = 0; i < (size_t)rank; ++i)
+ size *= cdims[i];
+ // print dataset info
+ printf("%s%s : nominal chunk size %lu [B] \n", base_path, name, size);
+ // get the allocated chunk sizes
+ if (H5Dchunk_iter(dset, H5P_DEFAULT, &chunk_cb, NULL) < 0) {
+ retval = -1;
+ goto fail_fig;
+ }
+
+fail_shape:
+ H5Sclose(dspace);
+fail_dspace:
+ H5Tclose(dtype);
+fail_dtype:;
+ }
+
+ H5Pclose(dcpl);
+fail_dcpl:
+ H5Dclose(dset);
+ }
+
+func_leave:
+ return retval;
+}
+//! <!-- [H5Ovisit_cb] -->
+
int
main(void)
{
@@ -166,7 +246,6 @@ fail_delete:
H5Fclose(file);
fail_file:;
}
-
//! <!-- [delete] -->
return ret_val;
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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ // 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;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ // clear the default error stack (for the current thread)
+ if (H5Eclear2(H5E_DEFAULT) < 0)
+ ret_val = EXIT_FAILURE;
+ }
+ //! <!-- [delete] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5F_examples.c b/doxygen/examples/H5F_examples.c
index a7ce6fb..4e89fde 100644
--- a/doxygen/examples/H5F_examples.c
+++ b/doxygen/examples/H5F_examples.c
@@ -10,7 +10,7 @@ main(void)
{
int ret_val = EXIT_SUCCESS;
- //! <!-- [life_cycle] -->
+ //! <!-- [create] -->
{
__label__ fail_fapl, fail_fcpl, fail_file;
hid_t fcpl, fapl, file;
@@ -48,12 +48,13 @@ fail_fapl:
H5Pclose(fcpl);
fail_fcpl:;
}
- //! <!-- [life_cycle] -->
+ //! <!-- [create] -->
- //! <!-- [life_cycle_w_open] -->
+ //! <!-- [read] -->
{
__label__ fail_fapl, fail_file;
- hid_t fapl, file;
+ hid_t fapl, file;
+ hsize_t size;
if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
@@ -63,7 +64,7 @@ fail_fcpl:;
// adjust the file access properties
}
- unsigned mode = H5F_ACC_RDWR;
+ unsigned mode = H5F_ACC_RDONLY;
char name[] = "f1.h5";
if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) {
@@ -71,14 +72,41 @@ fail_fcpl:;
goto fail_file;
}
- // do something useful with FILE
+ if (H5Fget_filesize(file, &size) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ printf("File size: %llu bytes\n", size);
H5Fclose(file);
fail_file:
H5Pclose(fapl);
fail_fapl:;
}
- //! <!-- [life_cycle_w_open] -->
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __label__ fail_file;
+ hid_t file;
+
+ unsigned mode = H5F_ACC_RDWR;
+ char name[] = "f1.h5";
+
+ if ((file = H5Fopen(name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ // create a cycle by hard linking the root group in the root group
+ if (H5Lcreate_hard(file, ".", file, "loopback", H5P_DEFAULT, H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+ H5Fclose(file);
+fail_file:;
+ }
+ //! <!-- [update] -->
//! <!-- [minimal] -->
{
@@ -183,5 +211,18 @@ fail_fapl:;
}
//! <!-- [mount] -->
+ //! <!-- [delete] -->
+ {
+#if H5_VERSION_GE(1, 12, 0)
+
+ // this function is only available in HDF5 1.12.x
+ if (H5Fdelete("f1.h5", H5P_DEFAULT) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+
+#endif
+ }
+ //! <!-- [delete] -->
+
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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ 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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ //! <!-- [create_ud] -->
+ 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:;
+ }
+ //! <!-- [create_ud] -->
+
+ //! <!-- [read_ud] -->
+ {
+ __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:;
+ }
+ //! <!-- [read_ud] -->
+
+ //! <!-- [update_ud] -->
+ {
+ __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:;
+ }
+ //! <!-- [update_ud] -->
+
+ //! <!-- [delete_ud] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete_ud] -->
+
+ 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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+//! <!-- [iter_cb] -->
+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;
+}
+//! <!-- [iter_cb] -->
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ 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 <stdio.h>
+#include <stdlib.h>
+
+#define H5P_DEFAULTx2 H5P_DEFAULT, H5P_DEFAULT
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5PL_examples.c b/doxygen/examples/H5PL_examples.c
new file mode 100644
index 0000000..d012d1b
--- /dev/null
+++ b/doxygen/examples/H5PL_examples.c
@@ -0,0 +1,97 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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");
+ printf("VOL plugins %s be loaded.\n", (mask & H5PL_VOL_PLUGIN) == 2 ? "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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ // replace "/tmp" with something more sensible
+ if (H5PLreplace("/foo/bar", 0) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ //! <!-- [create_class] -->
+ {
+ __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:;
+ }
+ //! <!-- [create_class] -->
+
+ //! <!-- [read_class] -->
+ {
+ __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:;
+ }
+ //! <!-- [read_class] -->
+
+ //! <!-- [update_class] -->
+ {
+ __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:;
+ }
+ //! <!-- [update_class] -->
+
+ //! <!-- [delete_class] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete_class] -->
+
+ 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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ 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 <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ 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 <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ __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:;
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ __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:;
+ }
+ //! <!-- [delete] -->
+
+ 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 <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+//! <!-- [filter] -->
+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;
+}
+//! <!-- [filter] -->
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ __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:;
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __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:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ // N/A
+ } //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+ // unregister the identity filter
+ if (H5Zunregister(256) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //! <!-- [delete] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/examples/H5_examples.c b/doxygen/examples/H5_examples.c
new file mode 100644
index 0000000..ef52ed0
--- /dev/null
+++ b/doxygen/examples/H5_examples.c
@@ -0,0 +1,85 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+//! <!-- [closing_shop] -->
+void
+closing_shop(void *ctx)
+{
+ printf("GoodBye, Cruel World!\n");
+}
+//! <!-- [closing_shop] -->
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [create] -->
+ {
+ // an HDF5 library instance is automatically initialized as
+ // part of the first HDF5 API call, but there's no harm in
+ // calling H5open().
+ if (H5open() < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //! <!-- [create] -->
+
+ //! <!-- [read] -->
+ {
+ __label__ fail_read;
+ unsigned majnum, minnum, relnum;
+ hbool_t flag;
+
+ // retrieve the library version
+ if (H5get_libversion(&majnum, &minnum, &relnum) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_read;
+ }
+ // is this a thread-safe library build?
+ if (H5is_library_threadsafe(&flag) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_read;
+ }
+
+ printf("Welcome to HDF5 %d.%d.%d\n", majnum, minnum, relnum);
+ printf("Thread-safety %s\n", (flag > 0) ? "enabled" : "disabled");
+
+fail_read:;
+ }
+ //! <!-- [read] -->
+
+ //! <!-- [update] -->
+ {
+ // update the library instance free list limits
+ if (H5set_free_list_limits(512 * 1024, 32 * 1024, 2048 * 1024, 128 * 1024, 8192 * 1024, 512 * 1024) <
+ 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //! <!-- [update] -->
+
+ //! <!-- [delete] -->
+ {
+#if H5_VERSION_GE(1, 13, 0)
+ // install a finalization routine
+ if (H5atclose(&closing_shop, NULL) < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+#endif
+ // close shop
+ if (H5close() < 0) {
+ ret_val = EXIT_FAILURE;
+ }
+ }
+ //! <!-- [delete] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
generated by cgit v0.12 at 2024-07-08 17:55:34 (GMT)