File (H5F)

HDF5 file access

Description

Use the MATLAB^® HDF5 file interface, H5F, to create, open, and close HDF5 files, and access information about them.

Functions

H5F.close

Close HDF5 file

H5F.close(fileID) terminates access to the HDF5 file identified by fileID and flushes all data to storage.

H5F.create

Create HDF5 file

fileID = H5F.create(filename) creates the file specified by specified by filename or by a uniform resource locator (URL) with the default library properties if the file does not already exist.

fileID = H5F.create(filename,flags,fcplID,faplID) creates the file specified by filename or by a URL with additional parameters.

 Details

Input Arguments

• filename — File name or uniform resource locator (URL), specified as a string scalar or character vector. For more information on working with remote data, see Work with Remote Data.

• flags — Flag that specifies whether to truncate the file or to fail if it already exists. Specify flags by one of the following string scalars or character vectors, or their numeric equivalent:

  • "H5F_ACC_TRUNC" — Overwrites any existing file with the same name.

  • "H5F_ACC_EXCL" — Does not overwrite an existing file with the same name.

• fcplID — File creation property list identifier. A value of "H5P_DEFAULT" indicates that the library should use default values for the appropriate property list.

• faplID — File access property list identifier. A value of "H5P_DEFAULT" indicates that the library should use default values for the appropriate property list.

Output Arguments

• fileID — Identifier of created file.

Limitations

• H5F.create does not support creating files stored remotely in HDFS™.

H5F.flush

Flush all data buffers to disk

H5F.flush(objID,scope) causes all buffers associated with a file to be immediately flushed to disk without removing the data from the cache.

 Details

Input Arguments

• objID — Any object identifier associated with the file, including the file itself, a dataset, a group, an attribute, or a named datatype.

• scope — value that specifies whether the scope of the flushing action is global or local. Specify scope as one of these values:

  • "H5F_SCOPE_GLOBAL" — Flushes the entire virtual file.

  • "H5F_SCOPE_LOCAL" — Flushes only the specified file.

H5F.get_access_plist

File access property list

faplID = H5F.get_access_plist(fileID) returns the file access property list identifier of the file specified by fileID.

H5F.get_create_plist

File creation property list

fcplID = H5F.get_create_plist(fileID) returns a file creation property list identifier identifying the creation properties used to create the file specified by fileID.

H5F.get_filesize

Size of HDF5 file

size = H5F.get_filesize(fileID) returns the size of the HDF5 file specified by fileID.

H5F.get_freespace

Amount of free space in file

freespace = H5F.get_freespace(fileID) returns the amount of space that is unused by any object in the file specified by fileID.

H5F.get_info

Global information about file

info = H5F.get_info(objID) returns global information for the file associated with the object identifier objID. For details about the fields of the info structure, please refer to the HDF5 documentation.

H5F.get_intent

Intended access mode of the HDF5 file

intent = H5F.get_intent(fileID) returns the intended access mode flag passed in with H5F.open when the file was opened.

 Details

Input Arguments

• fileID — File identifier for the currently open HDF5 file.

Output Arguments

• intent — Intended access mode flag originally passed in with H5F.open. Valid values are:

  • "H5F_ACC_RDONLY" — File was opened with read-only access. The numeric equivalent is 0.

  • "H5F_ACC_RDWR" — File was opened with read/write access. The numeric equivalent is 1.

  • "H5F_ACC_RDONLY"|"H5F_ACC_SWMR_READ" — File was opened with read-only access for a single-writer/multiple-reader (SWMR) scenario. The numeric equivalent is 64.

  • "H5F_ACC_RDWR"|"H5F_ACC_SWMR_WRITE" — File was opened with read/write access for a single-writer/multiple-reader (SWMR) scenario. The numeric equivalent is 33.

H5F.get_mdc_config

Metadata cache configuration

config = H5F.get_mdc_config(fileID) returns the current metadata cache configuration for the target file.

H5F.get_mdc_hit_rate

Metadata cache hit-rate

hitRate = H5F.get_mdc_hit_rate(fileID) queries the metadata cache of the target file to obtain its hit-rate since the last time hit-rate statistics were reset. If the cache has not been accessed since the last time the hit-rate statistics were reset, the hit-rate is defined to be 0.0.

The hit-rate is calculated as the number of cache hits divided by the sum of cache hits and cache misses.

H5F.get_mdc_size

Metadata cache size data

[maxsize,minsize,currentSize,entries] = H5F.get_mdc_size(fileID) queries the metadata cache of the target file to obtain current metadata cache size information.

 Details

Output Arguments

• maxsize — Current maximum size of the cache.

• minsize — Current minimum clean size of the cache.

• currentSize — Current cache size.

• entries — Current number of entries in the cache.

H5F.get_metadata_read_retry_info

List of read retries for metadata entries

retryInfo = H5F.get_metadata_read_retry_info(fileID) returns a cell array of numeric vectors containing information regarding the number of read retries for metadata entries with checksum for the file fileID.

H5F.get_name

Name of HDF5 file

name = H5F.get_name(objID) returns the name of the file to which the object specified by objID belongs. The object can be a group, dataset, attribute, or named data type.

H5F.get_obj_count

Number of open objects in HDF5 file

objcount = H5F.get_obj_count(fileID,types) returns the number of open object identifiers in fileID that are of type types.

 Details

Input Arguments

• fileID — File identifier.

• types — Datatype of object. Specify types as one or more of the following string scalars or character vectors, or their numeric equivalents. Separate multiple choices using the logical OR (|) operator.

  • "H5F_OBJ_FILE" — Return number of open file identifiers.

  • "H5F_OBJ_DATASET" — Return number of open dataset identifiers.

  • "H5F_OBJ_GROUP" — Return number of open group identifiers.

  • "H5F_OBJ_DATATYPE" — Return number of open named datatype identifiers.

  • "H5F_OBJ_ATTR" — Return number of open attribute identifiers.

  • "H5F_OBJ_ALL" — Return number of all open object types.

  • "H5F_OBJ_LOCAL" — Restrict search to objects opened through current file identifier. Use this option in combination with one or more other options.

H5F.get_obj_ids

List of open HDF5 file objects

[numobjIDs,objIDList] = H5F.get_obj_ids(fileID,types,maxObjs) returns a list of all open object identifiers in fileID that are of type specified by types.

 Details

Input Arguments

• fileID — File identifier.

• types — Datatype of object. Specify types as one or more of the following string scalars or character vectors, or their numeric equivalents. Separate multiple choices using the logical OR (|) operator.

  • "H5F_OBJ_FILE" — Return open file identifiers.

  • "H5F_OBJ_DATASET" — Return open dataset identifiers.

  • "H5F_OBJ_GROUP" — Return open group identifiers.

  • "H5F_OBJ_DATATYPE" — Return open named datatype identifiers.

  • "H5F_OBJ_ATTR" — Return open attribute identifiers.

  • "H5F_OBJ_ALL" — Return all open object types.

  • "H5F_OBJ_LOCAL" — Restrict search to objects opened through current file identifier. Use this option in combination with one or more other options.

• maxObjs — Maximum number of object identifiers to return. Specify maxObjs as a negative number to return all object identifiers for the file.

Output Arguments

• numObjIDs — Total number of objects in the list.

• objIDList — List of open object identifiers.

H5F.is_hdf5

Determine if file is HDF5

output = H5F.is_hdf5(filename) returns a positive value if the file specified by filename is in the HDF5 format, and 0 if it is not. A negative return value indicates a failure (including the case where filename does not exist).

 Details

Note

When reading data from remote locations, you must specify filename as the full path to an HDF5 file using a uniform resource locator (URL). For example, to read a dataset in an HDF5 file from Amazon S3™, specify the full URL for the file:

value = H5F.is_hdf5("s3://bucketname/path_to_file/example.h5");

For more information on accessing remote data, see Work with Remote Data.

H5F.mount

Mount HDF5 file onto specified location

H5F.mount(locID,name,childID,plistID) mounts the file specified by childID onto the group specified by locID and name using the mount properties specified by plistID.

 Details

Input Arguments

• locID — File, group, dataset, named datatype or attribute identifier associated with name.

• name — Name of group onto which file specified by childID is to be mounted.

• childID — File identifier of the file to be mounted.

• plistID — File mount property list identifier.

H5F.open

Open HDF5 file

fileID = H5F.open(filename) opens the file specified by filename or a uniform resource locator (URL) for read-only access.

fileID = H5F.open(filename,flags,faplID) opens the file specified by filename or a uniform resource locator (URL), and using the file access mode specified by flags and the file access property list identifier faplID.

 Details

Input Arguments

• filename — File name or a uniform resource locator (URL). For more information on working with remote data, see Work with Remote Data.

• flags — File access flag, specified as one of these string scalars or character vectors, or their numeric equivalents:

  • "H5F_ACC_RDWR" — Read-write mode. The numeric equivalent is 0.

  • "H5F_ACC_RDONLY" — Read-only mode. The numeric equivalent is 1.

  • "H5F_ACC_RDWR | H5F_ACC_SWMR_WRITE" — File is open for writing in a Single-Writer/Multiple-Reader (SWMR) scenario. The numeric equivalent is 64.

  • "H5F_ACC_RDONLY | H5F_ACC_SWMR_READ" — File is open for reading in a Single-Writer/ Multi-Reader (SWMR) scenario. The numeric equivalent is 33.

• faplID — File access property list identifier, specified as "H5P_DEFAULT", in which case the default I/O settings are used.

Output Arguments

• fileID — Identifier of opened file.

Limitations

• H5F.open does not support reading or writing to files stored remotely in HDFS when you specify the file access flag as "H5F_ACC_RDWR".

• When you specify the file access flag as "H5F_ACC_RDWR | H5F_ACC_SWMR_WRITE" or "H5F_ACC_RDONLY | H5F_ACC_SWMR_READ", you must follow this SWMR implementation scope:

  1. The writer process is only allowed to modify raw data of existing datasets by:

     • Appending data along an unlimited dimension

     • Modifying existing data

  2. The writer process is not allowed to:

     • Add new objects to or delete objects from the file. Such objects include groups, datasets, links, committed datatypes, and attributes.

     • Modify or append to any data items containing variable-size data types (including string data types).

  3. File space recycling is not allowed. The size of a file modified by a SWMR writer may be greater than if a non-SWMR writer had modified the file.

H5F.reopen

Reopen HDF5 file

newfileID = H5F.reopen(fileID) returns a new file identifier for the open HDF5 file specified by fileID.

H5F.set_mdc_config

Configure HDF5 file metadata cache

H5F.set_mdc_config(fileID,config) attempts to configure the metadata cache of the file according to the configuration structure, config. Before using this function, you should retrieve the current configuration using H5F.get_mdc_config.

H5F.start_swmr_write

Enable Single-Writer/Multiple-Reader writing mode

H5F.start_swmr_write(fileID) activates the Single-Writer/Multiple-Reader (SWMR) writing mode for the file specified by fileID.

 Details

Limitations

• You must follow this SWMR implementation scope:

  1. The writer process is only allowed to modify raw data of existing datasets by:

     • Appending data along an unlimited dimension

     • Modifying existing data

  2. The writer process is not allowed to:

     • Add new objects to or delete objects from the file. Such objects include groups, datasets, links, committed datatypes, and attributes.

     • Modify or append to any data items containing variable-size data types (including string data types).

  3. File space recycling is not allowed. The size of a file modified by a SWMR writer may be greater than if a non-SWMR writer had modified the file.

H5F.unmount

Unmount file or group from mount point

H5F.unmount(locID,name) disassociates the file or group specified by locID from the mount point specified by name. locID can be a file or group identifier.

Examples

Create HDF5 File

fid = H5F.create("myfile.h5");
H5F.close(fid);

Open HDF5 File

fid = H5F.open("example.h5");
H5F.close(fid);

Version History

Introduced before R2006a

R2021b: Support for Single-Writer/Multiple-Reader (SWMR) mode

• You can use H5F.get_intent to get the intended access mode of an HDF5 file that was opened with H5F.open.

• You can use the file access flags "H5F_ACC_RDWR | H5F_ACC_SWMR_WRITE" and "H5F_ACC_RDONLY | H5F_ACC_SWMR_READ" with H5F.open to open files in SWMR scenarios.

• You can use H5F.start_swmr_write to enable SWMR mode on a file.

R2021b: Fine-tune the metadata cache

You can use H5F.get_metadata_read_retry_info to retrieve information about the number of read retries for metadata entries.

R2020b: Work with HDF5 files at a remote location

You can use H5F.create or H5F.open to create or open, respectively, HDF5 files in remote locations, such as Amazon S3, Windows Azure^® Blob Storage, and HDFS.

R2020b: Work with HDF5 files with Unicode names

You can use H5F.create or H5F.open to create or open, respectively, HDF5 files whose names are encoded as Unicode characters.