Identifier (H5I)

HDF5 object identifiers

Description

Use the MATLAB^® HDF5 identifier interface, H5I, to handle HDF5 identifiers and access information about them.

HDF5 identifiers uniquely identify common HDF5 resources, such as files, groups, datasets, dataspaces, attributes and properties. They are returned by the functions that create or open these resources and are passed to functions that operate on or with these resources. You must close an object identifier after it is processed.

Functions

H5I.dec_ref

Decrement reference count

refcount = H5I.dec_ref(objID) decrements the reference count of the object specified by objID and returns the new count.

H5I.get_file_id

File identifier for specified object

fileID = H5I.get_file_id(objID) returns the identifier of the file associated with the object specified by objID.

H5I.get_name

Name of object

name = H5I.get_name(objID) returns the name of the group, dataset, or datatype specified by objID. If no name is attached to the object, H5I.get_name returns an empty character vector.

name = H5I.get_name(objID,"TextEncoding",encoding) additionally specifies the text encoding to use to interpret the object name.

 Details

Input Arguments

• objID — Group, dataset, or datatype identifier.

• encoding — Text encoding, specified as one of these values:

  • "system" — Use the system default encoding to interpret the object name. "system" is the default value of "TextEncoding".

  • "UTF-8" — Use UTF-8 encoding to interpret the object name.

Note

Starting in R2020a, the H5I.get_name function only accepts committed (previously called named) HDF5 datatypes as input arguments, and will error if you pass other datatypes as input. In releases R2019b and earlier, H5I.get_name does not error if you pass other datatypes as input.

To verify that the input is a committed HDF5 datatype, call the H5T.committed function on it. The H5T.committed function returns a value of 1 if the input is a committed HDF5 datatype, and a value of 0 if it is not.

H5I.get_ref

Reference count of object

refcount = H5I.get_ref(objID) returns the reference count of the object specified by objID.

H5I.get_type

Type of object

objtype = H5I.get_type(objID) returns the type of the object identified by objID.

 Details

Output Arguments

• objtype — Object type, returned as one of these:

  • H5I_FILE

  • H5I_GROUP

  • H5I_DATATYPE

  • H5I_DATASPACE

  • H5I_DATASET

  • H5I_ATTR

  • H5I_BADID

H5I.inc_ref

Increment reference count of specified object

refcount = H5I.inc_ref(objID) increments the reference count of the object specified by objID and returns the new count.

H5I.is_valid

Determine if specified identifier is valid

output = H5I.is_valid(objID) returns a positive value if the identifier objID is valid, and 0 if it is not.

Examples

Get File Identifier of Object

fid = H5F.open("example.h5");
gid = H5G.open(fid,"/g4");
fid2 = H5I.get_file_id(gid);
name = H5F.get_name(fid2);
fprintf("The filename is %s.\n",name);
H5G.close(gid);
H5F.close(fid);
H5F.close(fid2);

Version History

Introduced before R2006a

R2021a: H5I.get_name accepts only named HDF5 datatypes as input arguments

The H5I.get_name function accepts only committed (previously called named) HDF5 datatypes as input arguments and generates an error if you pass noncommitted datatypes as input.