 |
HDF5 1.14.5
API Reference
|
|
HDF5 1.14.5
API Reference
|
Use the functions in this module to manage HDF5 datatypes.
HDF5 datatypes describe the element type of HDF5 datasets and attributes. There's a large set of predefined datatypes, but users may find it useful to define new datatypes through a process called derivation.
The element type is automatically persisted as part of the HDF5 metadata of attributes and datasets. Additionally, datatype definitions can be persisted to HDF5 files and linked to groups as HDF5 datatype objects or so-called committed datatypes.
Modules | |
| Array Datatypes | |
| Atomic Datatypes | |
| Compound and Enumeration Datatypes | |
| Conversion Function | |
| Opaque Datatypes | |
| Predefined Datatypes | |
| Variable-length Sequence Datatypes | |
Macros | |
| #define | H5Tcommit H5Tcommit2 |
| #define | H5Topen H5Topen2 |
Functions | |
| hid_t | H5Tcreate (H5T_class_t type, size_t size) |
| Creates a new datatype. | |
| hid_t | H5Tcopy (hid_t type_id) |
| Copies an existing datatype. | |
| herr_t | H5Tclose (hid_t type_id) |
| Releases a datatype. | |
| herr_t | H5Tclose_async (hid_t type_id, hid_t es_id) |
| Asynchronous version of H5Tclose(). | |
| htri_t | H5Tequal (hid_t type1_id, hid_t type2_id) |
| Determines whether two datatype identifiers refer to the same datatype. | |
| herr_t | H5Tlock (hid_t type_id) |
| Locks a datatype. | |
| herr_t | H5Tcommit2 (hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id) |
| Commits a transient datatype, linking it into the file and creating a new committed datatype. | |
| herr_t | H5Tcommit_async (hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t es_id) |
| Asynchronous version of H5Tcommit2(). | |
| hid_t | H5Topen2 (hid_t loc_id, const char *name, hid_t tapl_id) |
| Opens a committed (named) datatype. | |
| hid_t | H5Topen_async (hid_t loc_id, const char *name, hid_t tapl_id, hid_t es_id) |
| Asynchronous version of H5Topen2(). | |
| herr_t | H5Tcommit_anon (hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id) |
| Commits a transient datatype to a file, creating a newly named datatype, but does not link it into the file structure. | |
| hid_t | H5Tget_create_plist (hid_t type_id) |
| Returns a copy of a datatype's creation property list. | |
| htri_t | H5Tcommitted (hid_t type_id) |
| Determines whether a datatype is a committed type or a transient type. | |
| herr_t | H5Tencode (hid_t obj_id, void *buf, size_t *nalloc) |
| Encodes a datatype object description into a binary buffer. | |
| hid_t | H5Tdecode (const void *buf) |
| Decodes a binary object description of datatype and returns a new object handle. | |
| herr_t | H5Tflush (hid_t type_id) |
| Flushes all buffers associated with a committed datatype to disk. | |
| herr_t | H5Trefresh (hid_t type_id) |
| Refreshes all buffers associated with a committed datatype. | |
| hid_t | H5Tget_super (hid_t type) |
| Returns the base datatype from which a datatype is derived. | |
| H5T_class_t | H5Tget_class (hid_t type_id) |
| Returns a datatype class. | |
| htri_t | H5Tdetect_class (hid_t type_id, H5T_class_t cls) |
| Determines whether a datatype contains any datatypes of the given datatype class. | |
| size_t | H5Tget_size (hid_t type_id) |
| Returns the size of a datatype. | |
| hid_t | H5Tget_native_type (hid_t type_id, H5T_direction_t direction) |
| Returns the native datatype identifier of a specified datatype. | |
| herr_t | H5Tset_size (hid_t type_id, size_t size) |
| Sets size for a datatype. | |
| herr_t | H5Tcommit1 (hid_t loc_id, const char *name, hid_t type_id) |
| Commits a transient datatype to a file, creating a newly named datatype. | |
| hid_t | H5Topen1 (hid_t loc_id, const char *name) |
| Opens a named datatype. | |
| #define H5Tcommit H5Tcommit2 |
H5Tcommit() is a macro that is mapped to either H5Tcommit1() or H5Tcommit2().
| #define H5Topen H5Topen2 |
H5Topen() is a macro that is mapped to either H5Topen1() or H5Topen2().
Releases a datatype.
| [in] | type_id | Datatype identifier |
H5Tclose() releases the datatype dtype_id. Further access through this datatype identifier is illegal. Failure to release a datatype with this call will result in resource leaks.
Asynchronous version of H5Tclose().
Commits a transient datatype to a file, creating a newly named datatype.
| [in] | loc_id | Location identifier. The identifier may be that of a file or group. |
| [in] | name | Name given to committed datatype |
| [in] | type_id | Identifier of datatype to be committed |
H5Tcommit1() commits the transient datatype (not immutable) to a file, turning it into a named datatype.
The datatype dtype_id is committed as a named datatype at the location loc_id, which is either a file or group identifier, with the name name.
name can be a relative path based at loc_id or an absolute path from the root of the file. Use of this function requires that any intermediate groups specified in the path already exist.
As is the case for any object in a group, the length of the name of a named datatype is not limited.
See H5Tcommit_anon() for a discussion of the differences between H5Tcommit() and H5Tcommit_anon().
This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
| herr_t H5Tcommit2 | ( | hid_t | loc_id, |
| const char * | name, | ||
| hid_t | type_id, | ||
| hid_t | lcpl_id, | ||
| hid_t | tcpl_id, | ||
| hid_t | tapl_id | ||
| ) |
Commits a transient datatype, linking it into the file and creating a new committed datatype.
| [in] | loc_id | Location identifier. The identifier may be that of a file or group. |
| [in] | name | Name given to committed datatype |
| [in] | type_id | Datatype identifier Identifier of datatype to be committed and, upon function's return, identifier for the committed datatype |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | tcpl_id | Datatype creation property list identifier |
| [in] | tapl_id | Datatype access property list identifier |
H5Tcommit2() saves a transient datatype as an immutable committed datatype in a file. The datatype specified by dtype_id is committed to the file with the name name at the location specified by loc_id and with the datatype creation and access property lists tcpl_id and tapl_id, respectively.
loc_id may be a file identifier, or a group identifier within that file. name may be either an absolute path in the file or a relative path from loc_id naming the newly-committed datatype.
The link creation property list, lcpl_id, governs creation of the link(s) by which the new committed datatype is accessed and the creation of any intermediate groups that may be missing.
Once committed, this datatype may be used to define the datatype of any other dataset or attribute in the file.
This function will not accept a datatype that cannot actually hold information. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
Committed datatypes are sometimes referred to as named datatypes.
Commits a transient datatype to a file, creating a newly named datatype, but does not link it into the file structure.
| [in] | loc_id | Location identifier. The identifier may be that of a file or group. |
| [in] | type_id | Datatype identifier |
| [in] | tcpl_id | Datatype creation property list identifier |
| [in] | tapl_id | Datatype access property list identifier |
H5Tcommit_anon() commits a transient datatype (not immutable) to a file, turning it into a named datatype with the specified creation and property lists. With default property lists, H5P_DEFAULT, H5Tcommit_anon() provides similar functionality to that of H5Tcommit(), with the differences described below.
H5P_DEFAULT can be passed in for the datatype creation property list identifier, tcpl_id. The datatype access property list identifier, tapl_id, is provided for future functionality and is not used at this time. This parameter should always be passed as the value H5P_DEFAULT.
Note that H5Tcommit_anon() does not link this newly-committed datatype into the file. After the H5Tcommit_anon() call, the datatype identifier type_id must be linked into the HDF5 file structure with H5Olink() or it will be deleted from the file when the file is closed.
The differences between this function and H5Tcommit() are as follows:
This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
| herr_t H5Tcommit_async | ( | hid_t | loc_id, |
| const char * | name, | ||
| hid_t | type_id, | ||
| hid_t | lcpl_id, | ||
| hid_t | tcpl_id, | ||
| hid_t | tapl_id, | ||
| hid_t | es_id | ||
| ) |
Asynchronous version of H5Tcommit2().
Determines whether a datatype is a committed type or a transient type.
| [in] | type_id | Datatype identifier |
H5Tcommitted() queries a type to determine whether the type specified by the dtype_id identifier is a committed (formerly known as a named) type or a transient type. If this function returns a positive value, then the type is committed (that is, it has been committed, perhaps by some other application). Datasets which return committed datatypes with H5Dget_type() are able to share the datatype with other datasets in the same file.
Copies an existing datatype.
| [in] | type_id | Datatype identifier |
H5Tcopy() makes a copy of an existing datatype. The returned type is always transient and unlocked.
The type_id argument can be either a datatype identifier, a predefined datatype (defined in H5Tpublic.h), or a dataset identifier. If type_id is a dataset identifier, this function returns a transient, modifiable datatype which is a copy of the dataset's datatype.
The returned datatype identifier should be released with H5Tclose() to prevent resource leaks.
| hid_t H5Tcreate | ( | H5T_class_t | type, |
| size_t | size | ||
| ) |
Creates a new datatype.
| [in] | type | Class of datatype to create |
| [in] | size | Size, in bytes, of the datatype being created |
H5Tcreate() creates a new datatype of the specified class with the specified number of bytes. This function is used only with the following datatype classes:
Other datatypes, including integer and floating-point datatypes, are typically created by using H5Tcopy() to copy and modify a predefined datatype.
When creating a variable-length string datatype, size must be H5T_VARIABLE; see Creating variable-length string datatypes.
When creating a fixed-length string datatype, size will be the length of the string in bytes. The length of the string in characters will depend on i the encoding used; see H5Pset_char_encoding.
ENUMs created with this function have a signed native integer base datatype. Use H5Tenum_create() if a different integer base datatype is required.
The datatype identifier returned from this function should be released with H5Tclose or resource leaks will result.
| hid_t H5Tdecode | ( | const void * | buf | ) |
Decodes a binary object description of datatype and returns a new object handle.
| [in] | buf | Buffer for the datatype object to be decoded |
H5Tdecode() Given an object description of datatype in binary in a buffer, H5Tdecode() reconstructs the HDF5 datatype object and returns a new object handle for it. The binary description of the object is encoded by H5Tencode(). User is responsible for passing in the right buffer.
The datatype identifier returned by this function can be released with H5Tclose() when the identifier is no longer needed so that resource leaks will not develop.
| htri_t H5Tdetect_class | ( | hid_t | type_id, |
| H5T_class_t | cls | ||
| ) |
Determines whether a datatype contains any datatypes of the given datatype class.
| [in] | type_id | Datatype identifier |
| [in] | cls | Datatype class |
H5Tdetect_class() determines whether the datatype specified in type_id contains any datatypes of the datatype class specified in dtype_class.
This function is useful primarily in recursively examining all the fields and/or base types of compound, array, and variable-length datatypes.
Valid class identifiers, as defined in H5Tpublic.h, are:
Encodes a datatype object description into a binary buffer.
| [in] | obj_id | Identifier of the object to be encoded |
| [in,out] | buf | Buffer for the object to be encoded into. |
| [in,out] | nalloc | IN: The size of the allocated buffer OUT: The size of the buffer needed |
H5Tencode() Given datatype identifier, H5Tencode() converts a datatype description into binary form in a buffer. Using this binary form in the buffer, a datatype object can be reconstructed using H5Tdecode() to return a new object handle (hid_t) for this datatype.
If the provided buffer is NULL, only the size of buffer needed is returned through nalloc.
A preliminary H5Tencode() call can be made to find out the size of the buffer needed. This value is returned as nalloc. That value can then be assigned to nalloc for a second H5Tencode() call, which will retrieve the actual encoded object.
If the library finds that nalloc is not big enough for the object, it simply returns the size of the buffer needed through nalloc without encoding the provided buffer.
Determines whether two datatype identifiers refer to the same datatype.
| [in] | type1_id | Datatype identifier |
| [in] | type2_id | Datatype identifier |
H5Tequal() determines whether two datatype identifiers refer to the same datatype.
Flushes all buffers associated with a committed datatype to disk.
| [in] | type_id | Datatype identifier |
H5Tflush() causes all buffers associated with a committed datatype type_id to be immediately flushed to disk without removing the data from the cache.
HDF5 does not possess full control over buffering. H5Tflush() flushes the internal HDF5 buffers and then asks the operating system (the OS) to flush the system buffers for the open files. After that, the OS is responsible for ensuring that the data is actually flushed to disk.
| H5T_class_t H5Tget_class | ( | hid_t | type_id | ) |
Returns a datatype class.
| [in] | type_id | Datatype identifier |
H5Tget_class() returns the class of the datatype type_id. Valid class identifiers, as defined in H5Tpublic.h, are:
Returns a copy of a datatype's creation property list.
| [in] | type_id | Datatype identifier |
H5Tget_create_plist() returns a property list identifier for the datatype creation property list associated with the datatype specified by type_id.
The creation property list identifier should be released with H5Pclose() to prevent memory leaks.
| hid_t H5Tget_native_type | ( | hid_t | type_id, |
| H5T_direction_t | direction | ||
| ) |
Returns the native datatype identifier of a specified datatype.
| [in] | type_id | Datatype identifier |
| [in] | direction | Direction of search |
H5Tget_native_type() returns the equivalent native datatype identifier for the datatype specified by type_id.
H5Tget_native_type() is designed primarily to facilitate the use of the H5Dread() function, for which users otherwise must undertake a multi-step process to determine the native datatype of a dataset prior to reading it into memory. This function can be used for the following purposes:
For example, if type_id is a compound datatype, the returned datatype identifier will be for a similar compound datatype with each element converted to the corresponding native datatype; nested compound datatypes will be unwound. If type_id is an array, the returned datatype identifier will be for the native datatype of a single array element.
H5Tget_native_type() selects the first matching native datatype from the following list:
The direction parameter indicates the order in which the library searches for a native datatype match. Valid values for direction are as follows:
H5Tget_native_type() is designed primarily for use with integer, floating point, and bitfield datatypes. String, time, opaque, and reference datatypes are returned as a copy of dtype_id. See above for compound, array, enumerated, and variable-length datatypes.
The identifier returned by H5Tget_native_type() should eventually be closed by calling H5Tclose() to release resources.
| size_t H5Tget_size | ( | hid_t | type_id | ) |
Returns the size of a datatype.
| [in] | type_id | Datatype identifier |
H5Tget_size() returns the size of a datatype in bytes.
sizeof(char *). This function does not return the size of actual variable-length string data. hvl_t struct, or sizeof(hvl_t). The hvl_t struct contains a pointer to the actual data and a size value. This function does not return the size of actual variable-length sequence data.Returns the base datatype from which a datatype is derived.
| [in] | type | Datatype identifier |
H5Tget_super() returns the base datatype from which the datatype type_id is derived. In the case of an enumeration type, the return value is an integer type.
The datatype identifier returned by this function must be released with H5Tclose() when the identifier is no longer needed so that resource leaks will not develop.
Locks a datatype.
| [in] | type_id | Datatype identifier |
H5Tlock() locks the datatype specified by the dtype_id identifier, making it read-only and non-destructible. This is normally done by the library for predefined datatypes so the application does not inadvertently change or delete a predefined type. Once a datatype is locked it can never be unlocked.
Opens a named datatype.
| [in] | loc_id | Location identifier. The identifier may be that of a file or group. |
| [in] | name | A datatype name, defined within the specified file or group |
H5Topen1() opens a named datatype at the location specified by loc_id and returns an identifier for the datatype. loc_id can be either a file or group identifier. The identifier should eventually be closed by calling H5Tclose() to release resources.
Opens a committed (named) datatype.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the datatype to open |
| [in] | tapl_id | Datatype access property list identifier |
H5Topen2() opens a committed datatype at the location specified by loc_id and returns an identifier for the datatype. loc_id is either a file or group identifier. The identifier should eventually be closed by calling H5Tclose() to release resources.
The committed datatype is opened with the datatype access property list tapl_id.
Asynchronous version of H5Topen2().
Refreshes all buffers associated with a committed datatype.
| [in] | type_id | Datatype identifier |
H5Trefresh() causes all buffers associated with a committed datatype to be cleared and immediately re-loaded with updated contents from disk.
This function essentially closes the datatype, evicts all metadata associated with it from the cache, and then reopens the datatype. The reopened datatype is automatically re-registered with the same identifier.
Sets size for a datatype.
| [in] | type_id | Datatype identifier |
| [in] | size | New datatype size in bytes or H5T_VARIABLE |
H5Tset_size() sets the total size, size, in bytes, for a datatype.
size must have a positive value unless it is passed in as H5T_VARIABLE and the datatype is a string datatype.
8*size.dtype_id is a variable-length string, size must normally be set to H5T_VARIABLE. See Creating variable-length string datatypes.
1.9.7