![]() |
HDF5
1.13.0
|
Functions | |
H5_DLL herr_t | H5Tclose (hid_t type_id) |
Releases a datatype. More... | |
H5_DLL herr_t | H5Tcommit2 (hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id) |
Commits a transient datatype, linking it into the file and creating a new committed datatype. More... | |
H5_DLL 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 new named datatype, but does not link it into the file structure. More... | |
H5_DLL htri_t | H5Tcommitted (hid_t type_id) |
Determines whether a datatype is a committed type or a transient type. More... | |
H5_DLL hid_t | H5Tcopy (hid_t obj_id) |
Copies an existing datatype. More... | |
H5_DLL hid_t | H5Tcreate (H5T_class_t class, size_t size) |
Creates a new datatype. More... | |
H5_DLL htri_t | H5Tdetect_class (hid_t type_id, H5T_class_t cls) |
Determines whether a datatype contains any datatypes of the given datatype class. More... | |
H5_DLL htri_t | H5Tequal (hid_t type1_id, hid_t type2_id) |
Determines whether two datatype identifiers refer to the same datatype. More... | |
H5_DLL herr_t | H5Tflush (hid_t type_id) |
Flushes all buffers associated with a committed datatype to disk. More... | |
H5_DLL H5T_class_t | H5Tget_class (hid_t type_id) |
Returns a datatype class. More... | |
H5_DLL hid_t | H5Tget_create_plist (hid_t type_id) |
Returns a copy of a datatype creation property list. More... | |
H5_DLL hid_t | H5Tget_native_type (hid_t dtype_id, H5T_direction_t direction) |
Returns the native datatype identifier of a specified datatype. More... | |
H5_DLL size_t | H5Tget_size (hid_t type_id) |
Returns the size of a datatype. More... | |
H5_DLL hid_t | H5Tget_super (hid_t type) |
Returns the base datatype from which a datatype is derived. More... | |
H5_DLL herr_t | H5Tlock (hid_t type_id) |
Locks a datatype. More... | |
H5_DLL hid_t | H5Topen2 (hid_t loc_id, const char *name, hid_t tapl_id) |
Opens a committed (named) datatype. More... | |
H5_DLL herr_t | H5Trefresh (hid_t type_id) |
Refreshes all buffers associated with a committed datatype. More... | |
H5_DLL herr_t | H5Tset_size (hid_t type_id, size_t size) |
Sets size for a datatype. More... | |
H5_DLL herr_t | H5Tcommit1 (hid_t loc_id, const char *name, hid_t type_id) |
Commits a transient datatype to a file, creating a new named datatype. More... | |
H5_DLL hid_t | H5Topen1 (hid_t loc_id, const char *name) |
Opens a named datatype. More... | |
Releases a datatype.
[in] | dtype_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.
Commits a transient datatype to a file, creating a new 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] | dtype_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.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | name | Name given to committed datatype |
[in] | dtype_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] | dtype_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 \tcpl_id \tapl_id |
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-commited 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 commited, this datatype may be used to define the datatype of any other dataset or attribute in the file.
This function will not accept a datatype that cannot actually hold information. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
Committed datatypes are sometimes referred to as named datatypes.
Commits a transient datatype to a file, creating a new 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] | dtype_id | Datatype identifier \tcpl_id \tapl_id |
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 dtype_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.
Determines whether a datatype is a committed type or a transient type.
[in] | dtype_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] | dtype_id | Datatype identifier |
H5Tcopy() makes a copy of an existing datatype. The returned type is always transient and unlocked.
The obj_id
argument can be either a datatype identifier, a predefined datatype (defined in H5Tpublic.h), or a dataset identifier. If obj_id
is a dataset identifier, this function returns a transient, modifiable datatype which is a copy of the dataset's datatype.
The returned datatype identifier should be released with H5Tclose() to prevent resource leak.
[in] | dtype_id | Datatype identifier |
H5Tcopy() makes a copy of an existing datatype. The returned type is always transient and unlocked.
The obj_id
argument can be either a datatype identifier, a predefined datatype (defined in H5Tpublic.h), or a dataset identifier. If obj_id
is a dataset identifier, this function returns a transient, modifiable datatype which is a copy of the dataset's datatype.
The returned datatype identifier should be released with H5Tclose() to prevent resource leak.
H5Tcopy returns H5I_INVALID_HID on fail; we will need to modify return macro to include H5I_INVALID_HID instead of "negative value".
Create an example for H5Tcopy.
[in] | obj_id | identifier; can be a datatype identifier, a predefined datatype, or a dataset identifier. |
H5Tcopy copies an existing datatype. The returned type is always transient and unlocked.
The obj_id
argument can be either a datatype identifier, a predefined datatype (defined in H5Tpublic.h), or a dataset identifier. If obj_id
is a dataset identifier,this function returns a transient, modifiable datatype which is a copy of the dataset's datatype.
The datatype identifier should be released with H5Tclose() or resource leak will occur.
hid_t H5Tcreate | ( | H5T_class_t | class, |
size_t | size | ||
) |
Creates a new datatype.
[in] | class | 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.
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.
Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tcreate.
[in] | class | 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.
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.
Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tcreate.
Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tcreate.
[in] | class | 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.
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.
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] | dtype_id | Datatype identifier param[in] dtype_class Datatype class |
H5Tdetect_class() determines whether the datatype specified in dtype_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:
Determines whether two datatype identifiers refer to the same datatype.
[in] | dtype_id1 | Datatype identifier |
[in] | dtype_id2 | Datatype identifier |
H5Tequal() determines whether two datatype identifiers refer to the same datatype.
Flushes all buffers associated with a committed datatype to disk.
[in] | dtype_id | Datatype identifier |
H5Tflush() causes all buffers associated with a committed datatype dtype_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] | dtype_id | Datatype identifier |
H5Tget_class() returns the class of the datatype dtype_id
. Valid class identifiers, as defined in H5Tpublic.h, are:
Returns a copy of a datatype creation property list.
[in] | dtype_id | Datatype identifier |
H5Tget_create_plist() returns a property list identifier for the datatype creation property list associated with the datatype specified by dtype_id
.
The creation property list identifier should be released with H5Pclose() to prevent memory leaks.
hid_t H5Tget_native_type | ( | hid_t | dtype_id, |
H5T_direction_t | direction | ||
) |
Returns the native datatype identifier of a specified datatype.
[in] | dtype_id | Datatype identifier param[in] direction Direction of search |
H5Tget_native_type() returns the equivalent native datatype identifier for the datatype specified by dtype_id
.
H5Tget_native_type() is designed primarily to facilitate use of the H5Dread() function, for which users otherwise must undertake a multi-step process to determine the native datatype of a dataset prior to reading it into memory. This function can be used for the following purposes:
For example, if dtype_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 dtype_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:
H5T_DIR_ASCEND | Searches the above list in ascending size of the datatype, i.e., from top to bottom. (Default) |
H5T_DIR_DESCEND | Searches the above list in descending size of the datatype, i.e., from bottom to top. |
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] | dtype_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.Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tget_size().
[in] | dtype_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.Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tget_size().
Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tget_size.
\type_id
H5Tget_size returns the size of a datatype in bytes.
For atomic datatypes, array datatypes, compound datatypes, and other datatypes of a constant size, the returned value is the size of the actual datatype in bytes.
For variable-length string datatypes the returned value is the size of the pointer to the actual string, or sizeof
(char
*
). This function does not return the size of actual variable-length string data.
For variable-length sequence datatypes (see H5Tvlen_create()), the returned value is the size of the 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] | dtype_id | Datatype identifier |
H5Tget_super() returns the base datatype from which the datatype dtype_id
is derived. In the case of an enumeration type, the return value is an integer type.
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.
Locks a datatype.
[in] | dtype_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 H5T_CLOSE to release resources.
[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 H5T_CLOSE 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 \tapl_id |
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.
Refreshes all buffers associated with a committed datatype.
[in] | dtype_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 re-opens the datatype. The reopened datatype is automatically re-registered with the same identifier.
Sets size for a datatype.
Sets size for a datatype. \type_id for which the size is being set.
[in] | dtype_id | Datatype identifier for which the size is being set |
[in] | size | New datatype size is 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.Create an example for H5Tset_size().
Original has a reference to “Creating variable-length string datatypes”.
[in] | dtype_id | Datatype identifier for which the size is being set |
[in] | size | New datatype size is 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.Create an example for H5Tset_size().
Original has a reference to “Creating variable-length string datatypes”.
Create an example for H5Tset_size().
Original has a reference to “Creating variable-length string datatypes”.
[in] | size | New datatype size is bytes or H5T_VARIABLE |
H5Tset_size() sets the total size in bytes, size
, for a datatype.
The parameter size
must have a positive value, unless it is passed as H5T_VARIABLE and the datatype is a string datatype.
Numeric datatypes: If the datatype is atomic and the size is decreased so that significant bits of the datatype extend beyond the edge of the new size, then the offset property of the datatype is decreased toward zero. If the offset becomes zero and the significant bits of the datatype still hang over the edge of the new size, then the number of significant bits is decreased.
String or character datatypes: The size set for a string datatype should include space for the null-terminator character, otherwise it will not be stored on (or retrieved from) disk. Adjusting the size of a string automatically sets the precision to 8*size
.
Variable-length string datatypes: If dtype_id
is a variable-length string, size must normally be set to H5T_VARIABLE.
Compound datatypes: This function may be used to increase or decrease the size of a compound datatype, but the function will fail if the new size is too small to accommodate all member fields.
Ineligible datatypes: This function cannot be used with enumerated datatypes (H5T_ENUM), array datatypes (H5T_ARRAY), variable-length array datatypes (H5T_VLEN), or reference datatypes (H5T_REFERENCE).