Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/
HDF5  1.12.1
H5T

Detailed Description

Datatype Interface.

Todo:
Describe concisely what the functions in this module are about.

Modules

 Array Datatypes
 
 Atomic Datatypes
 
 Compound Datatypes
 
 Conversion Function
 
 Enumeration Datatypes
 
 Opaque Datatypes
 
 Predefined Datatypes
 
 Variable-length Sequence Datatypes
 

Functions

hid_t H5Tcreate (H5T_class_t type, size_t size)
 Creates a new datatype. More...
 
hid_t H5Tcopy (hid_t type_id)
 Copies an existing datatype. More...
 
herr_t H5Tclose (hid_t type_id)
 Releases a datatype. More...
 
htri_t H5Tequal (hid_t type1_id, hid_t type2_id)
 Determines whether two datatype identifiers refer to the same datatype. More...
 
herr_t H5Tlock (hid_t type_id)
 Locks a datatype. More...
 
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...
 
hid_t H5Topen2 (hid_t loc_id, const char *name, hid_t tapl_id)
 Opens a committed (named) datatype. More...
 
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...
 
hid_t H5Tget_create_plist (hid_t type_id)
 Returns a copy of a datatype's creation property list. More...
 
htri_t H5Tcommitted (hid_t type_id)
 Determines whether a datatype is a committed type or a transient type. More...
 
herr_t H5Tencode (hid_t obj_id, void *buf, size_t *nalloc)
 Encodes a datatype object description into a binary buffer. More...
 
hid_t H5Tdecode (const void *buf)
 Decodes a binary object description of datatype and return a new object handle. More...
 
herr_t H5Tflush (hid_t type_id)
 Flushes all buffers associated with a committed datatype to disk. More...
 
herr_t H5Trefresh (hid_t type_id)
 Refreshes all buffers associated with a committed datatype. More...
 
hid_t H5Tget_super (hid_t type)
 Returns the base datatype from which a datatype is derived. More...
 
H5T_class_t H5Tget_class (hid_t type_id)
 Returns a datatype class. More...
 
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...
 
size_t H5Tget_size (hid_t type_id)
 Returns the size of a datatype. More...
 
hid_t H5Tget_native_type (hid_t type_id, H5T_direction_t direction)
 Returns the native datatype identifier of a specified datatype. More...
 
herr_t H5Tset_size (hid_t type_id, size_t size)
 Sets size for a datatype. More...
 
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...
 
hid_t H5Topen1 (hid_t loc_id, const char *name)
 Opens a named datatype. More...
 

Function Documentation

◆ H5Tclose()

herr_t H5Tclose ( hid_t  type_id)

Releases a datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

◆ H5Tcommit1()

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.

Parameters
[in]loc_idLocation identifier. The identifier may be that of a file or group.
[in]nameName given to committed datatype
[in]type_idIdentifier of datatype to be committed
Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Deprecated:
This function has been renamed from H5Tcommit() and is deprecated in favor of the macro H5Tcommit or the function H5Tcommit2().

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.

Version
1.8.7 Function modified in this release to reject datatypes that will not accommodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members.
1.8.0 C function H5Tcommit() renamed to H5Tcommit1() and deprecated in this release.
Since
1.2.0

◆ H5Tcommit2()

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.

Parameters
[in]loc_idLocation identifier. The identifier may be that of a file or group.
[in]nameName given to committed datatype
[in]type_idDatatype identifier Identifier of datatype to be committed and, upon function’s return, identifier for the committed datatype
[in]lcpl_idLink creation property list identifier
[in]tcpl_idDatatype creation property list identifier
[in]tapl_idDatatype access property list identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Version
1.8.7 Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members.
Since
1.8.0

◆ H5Tcommit_anon()

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.

Parameters
[in]loc_idLocation identifier. The identifier may be that of a file or group.
[in]type_idDatatype identifier
[in]tcpl_idDatatype creation property list identifier
[in]tapl_idDatatype access property list identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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:

  • H5Tcommit_anon() explicitly includes property lists, which provides for greater control of the creation process and of the properties of the new named datatype. H5Tcommit() always uses default properties.
  • H5Tcommit_anon() neither provides the new named datatype’s name nor links it into the HDF5 file structure; those actions must be performed separately through a call to H5Olink(), which offers greater control over linking.

This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.

Version
1.8.7 Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members.
Since
1.2.0

◆ H5Tcommitted()

htri_t H5Tcommitted ( hid_t  type_id)

Determines whether a datatype is a committed type or a transient type.

Parameters
[in]type_idDatatype identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

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.

Version
1.8.0 Fortran API was added
Since
1.6 or earlier

◆ H5Tcopy()

hid_t H5Tcopy ( hid_t  type_id)

Copies an existing datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

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 leak.

◆ H5Tcreate()

hid_t H5Tcreate ( H5T_class_t  type,
size_t  size 
)

Creates a new datatype.

Parameters
[in]typeClass of datatype to create
[in]sizeSize, in bytes, of the datatype being created
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

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.

See also
H5Tclose()
Since
1.2.0

◆ H5Tdecode()

hid_t H5Tdecode ( const void *  buf)

Decodes a binary object description of datatype and return a new object handle.

Parameters
[in]bufBuffer for the datatype object to be decoded
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

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.

◆ H5Tdetect_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.

Parameters
[in]type_idDatatype identifier
[in]clsDatatype class
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

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:

Since
1.6.0

◆ H5Tencode()

herr_t H5Tencode ( hid_t  obj_id,
void *  buf,
size_t *  nalloc 
)

Encodes a datatype object description into a binary buffer.

Parameters
[in]obj_idIdentifier of the object to be encoded
[in,out]bufBuffer for the object to be encoded into.
[in,out]nallocIN: The size of the allocated buffer OUT: The size of the buffer needed
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.2.0

◆ H5Tequal()

htri_t H5Tequal ( hid_t  type1_id,
hid_t  type2_id 
)

Determines whether two datatype identifiers refer to the same datatype.

Parameters
[in]type1_idDatatype identifier
[in]type2_idDatatype identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Tequal() determines whether two datatype identifiers refer to the same datatype.

Since
1.6 or earlier

◆ H5Tflush()

herr_t H5Tflush ( hid_t  type_id)

Flushes all buffers associated with a committed datatype to disk.

Parameters
[in]type_idDatatype identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Since
1.10.0 C function introduced with this release.
See also
H5Dflush() H5Drefresh() H5Tflush() H5Grefresh() H5Oflush() H5Orefresh() H5Tflush() H5Trefresh() H5Fstart_swmr_write() H5Pget_append_flush() H5Pget_object_flush_cb() H5Pset_append_flush() H5Pset_object_flush_cb()

◆ H5Tget_class()

H5T_class_t H5Tget_class ( hid_t  type_id)

Returns a datatype class.

Parameters
[in]type_idDatatype identifier
Returns
Returns the datatype class if successful; otherwise H5T_NO_CLASS.

H5Tget_class() returns the class of the datatype type_id. Valid class identifiers, as defined in H5Tpublic.h, are:

Note
The library returns H5T_STRING for both fixed-length and variable-length strings.
Unsupported datatype: The time datatype class, H5T_TIME, is not supported. If H5T_TIME is used, the resulting data will be readable and modifiable only on the originating computing platform; it will not be portable to other platforms.

◆ H5Tget_create_plist()

hid_t H5Tget_create_plist ( hid_t  type_id)

Returns a copy of a datatype's creation property list.

Parameters
[in]type_idDatatype identifier
Returns
Returns a datatype creation property list identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Since
1.8.0

◆ H5Tget_native_type()

hid_t H5Tget_native_type ( hid_t  type_id,
H5T_direction_t  direction 
)

Returns the native datatype identifier of a specified datatype.

Parameters
[in]type_idDatatype identifier
[in]directionDirection of search
Returns
Returns a native datatype identifier if successful; otherwise returns H5I_INVALID_HID.

H5Tget_native_type() returns the equivalent native datatype identifier for the datatype specified by type_id.

H5Tget_native_type() is designed primarily to facilitate use of the H5Dread() function, for which users otherwise must undertake a multi-step process to determine the native datatype of a dataset prior to reading it into memory. This function can be used for the following purposes:

  • To determine the native datatype of an atomic datatype
  • To determine the base datatype of an array, enumerated, or variable-length datatype
  • To determine the native atomic datatypes of the individual components of a compound datatype

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.

Note
Please note that a datatype is actually an object identifier or handle returned from opening the datatype. It is not persistent and its value can be different from one HDF5 session to the next.
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.
Since
1.6.0

◆ H5Tget_size()

size_t H5Tget_size ( hid_t  type_id)

Returns the size of a datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns the size of the datatype in bytes if successful; otherwise, returns 0.

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.
See also
H5Tset_size()
Since
1.2.0

◆ H5Tget_super()

hid_t H5Tget_super ( hid_t  type)

Returns the base datatype from which a datatype is derived.

Parameters
[in]typeDatatype identifier
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

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.

◆ H5Tlock()

herr_t H5Tlock ( hid_t  type_id)

Locks a datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

◆ H5Topen1()

hid_t H5Topen1 ( hid_t  loc_id,
const char *  name 
)

Opens a named datatype.

Parameters
[in]loc_idLocation identifier. The identifier may be that of a file or group.
[in]nameA datatype name, defined within the specified file or group
Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Deprecated:
This function has been renamed from H5Topen() and is deprecated in favor of the macro H5Topen or the function H5Topen2().

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.

Version
1.8.0 Function H5Topen() renamed to H5Topen1() and deprecated in this release.
Since
1.2.0

◆ H5Topen2()

hid_t H5Topen2 ( hid_t  loc_id,
const char *  name,
hid_t  tapl_id 
)

Opens a committed (named) datatype.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the datatype to open
[in]tapl_idDatatype access property list identifier
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Since
1.8.0

◆ H5Trefresh()

herr_t H5Trefresh ( hid_t  type_id)

Refreshes all buffers associated with a committed datatype.

Parameters
[in]type_idDatatype identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.2.0

◆ H5Tset_size()

herr_t H5Tset_size ( hid_t  type_id,
size_t  size 
)

Sets size for a datatype.

Parameters
[in]type_idDatatype identifier
[in]sizeNew datatype size is bytes or H5T_VARIABLE
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

  • 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. See Creating variable-length string datatypes.
  • 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).
See also
H5Tget_size()
Since
1.2.0
H5T_ENUM
@ H5T_ENUM
Definition: H5Tpublic.h:42
H5T_BITFIELD
@ H5T_BITFIELD
Definition: H5Tpublic.h:38
H5T_DIR_DEFAULT
@ H5T_DIR_DEFAULT
Definition: H5Tpublic.h:199
H5T_VLEN
@ H5T_VLEN
Definition: H5Tpublic.h:43
H5T_ARRAY
@ H5T_ARRAY
Definition: H5Tpublic.h:44
H5T_OPAQUE
@ H5T_OPAQUE
Definition: H5Tpublic.h:39
H5T_NO_CLASS
@ H5T_NO_CLASS
Definition: H5Tpublic.h:33
H5T_COMPOUND
@ H5T_COMPOUND
Definition: H5Tpublic.h:40
H5T_NCLASSES
@ H5T_NCLASSES
Definition: H5Tpublic.h:46
H5T_REFERENCE
@ H5T_REFERENCE
Definition: H5Tpublic.h:41
H5T_FLOAT
@ H5T_FLOAT
Definition: H5Tpublic.h:35
H5T_direction_t
H5T_direction_t
Definition: H5Tpublic.h:198
H5T_STRING
@ H5T_STRING
Definition: H5Tpublic.h:37
H5T_DIR_ASCEND
@ H5T_DIR_ASCEND
Definition: H5Tpublic.h:200
H5T_TIME
@ H5T_TIME
Definition: H5Tpublic.h:36
H5T_DIR_DESCEND
@ H5T_DIR_DESCEND
Definition: H5Tpublic.h:201
H5T_INTEGER
@ H5T_INTEGER
Definition: H5Tpublic.h:34
H5T_class_t
H5T_class_t
Definition: H5Tpublic.h:32