HDF5 C++ API Reference Manual

- Main Page
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

# H5::H5File Class Reference

`#include <H5File.h>`

Inheritance diagram for H5::H5File:

List of all members.

## Public Member Functions
| H5File (const char *name, unsigned int flags, const FileCreatPropList &create_plist=FileCreatPropList::DEFAULT, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
| Creates or opens an HDF5 file depending on the parameter flags.
| H5File (const H5std_string &name, unsigned int flags, const FileCreatPropList &create_plist=FileCreatPropList::DEFAULT, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
| This is another overloaded constructor. It differs from the above constructor only in the type of the name argument.
void | openFile (const H5std_string &name, unsigned int flags, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
| This is an overloaded member function, provided for convenience. It takes an `H5std_string` for name.
void | openFile (const char *name, unsigned int flags, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
| Opens an HDF5 file.
virtual void | close ()
| Closes this HDF5 file.
void | flush (H5F_scope_t scope) const
| Flushes all buffers associated with a file to disk.
FileAccPropList | getAccessPlist () const
| Returns the access property list of this file.
FileCreatPropList | getCreatePlist () const
| Returns the creation property list of this file.
H5std_string | getFileName () const
| Gets the name of this file.
hsize_t | getFileSize () const
| Returns the file size of the HDF5 file.
hssize_t | getFreeSpace () const
| Returns the amount of free space in the file.
ssize_t | getObjCount (unsigned types) const
| Returns the number of opened object IDs (files, datasets, groups and datatypes) in the same file.
ssize_t | getObjCount () const
| This is an overloaded member function, provided for convenience. It takes no parameter and returns the object count of all object types.
void | getObjIDs (unsigned types, size_t max_objs, hid_t *oid_list) const
| Retrieves a list of opened object IDs (files, datasets, groups and datatypes) in the same file.
H5G_obj_t | getRefObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
| Retrieves the type of object that an object reference points to.
H5G_obj_t | getObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
| This function was misnamed and will be deprecated in favor of H5File::getRefObjType; please use getRefObjType instead.
DataSpace | getRegion (void *ref, H5R_type_t ref_type=H5R_DATASET_REGION) const
| Retrieves a dataspace with the region pointed to selected.
void | getVFDHandle (FileAccPropList &fapl, void **file_handle) const
| Returns the pointer to the file handle of the low-level file driver.
void | getVFDHandle (void **file_handle) const
| This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.
void | reOpen ()
| Reopens this file.
void | reopen ()
| Reopens this file.
void | reference (void *ref, const char *name, const DataSpace &dataspace, H5R_type_t ref_type=H5R_DATASET_REGION) const
| Creates a reference to an HDF5 object or a dataset region.
void | reference (void *ref, const char *name) const
| This is an overloaded function, provided for your convenience. It differs from the above function in that it only creates a reference to an HDF5 object, not to a dataset region.
void | reference (void *ref, const H5std_string &name) const
| This is an overloaded function, provided for your convenience. It differs from the above function in that it takes an `H5std_string` for the object's name.
virtual H5std_string | fromClass () const
virtual void | throwException (const H5std_string &func_name, const H5std_string &msg) const
| Throws file exception - initially implemented for CommonFG.
virtual hid_t | getLocId () const
| H5File ()
| Default constructor: creates a stub H5File object.
| H5File (const H5File &original)
| Copy constructor: makes a copy of the original H5File object.
virtual hid_t | getId () const
virtual | ~H5File ()
| Properly terminates access to this file.
## Static Public Member Functions
static bool | isHdf5 (const char *name)
| Determines whether a file in HDF5 format.
static bool | isHdf5 (const H5std_string &name)
| This is an overloaded member function, provided for convenience. It takes an `H5std_string` for name.
## Protected Member Functions
virtual void | p_setId (const hid_t new_id)
| Sets the identifier of this HDF5 file to a new value.

## Detailed Description

Examples:

  chunks.cpp, compound.cpp, create.cpp, extend_ds.cpp, h5group.cpp, readdata.cpp, and writedata.cpp.

## Constructor & Destructor Documentation

H5::H5File::H5File | ( | const char * | name,
|  | unsigned int | flags,
|  | const FileCreatPropList & | create_plist = `FileCreatPropList::DEFAULT`,
|  | const FileAccPropList & | access_plist = `FileAccPropList::DEFAULT` |
| ) |  |  |

Creates or opens an HDF5 file depending on the parameter flags.

Parameters:

  | name | - IN: Name of the file
  | flags | - IN: File access flags
  | create_plist | - IN: File creation property list, used when modifying default file meta-data. Default to FileCreatPropList::DEFAULT
  | access_plist | - IN: File access property list. Default to FileCreatPropList::DEFAULT

Description
  Valid values of flags include:
  - `H5F_ACC_TRUNC` - Truncate file, if it already exists, erasing all data previously stored in the file.
  - `H5F_ACC_EXCL` - Fail if file already exists. `H5F_ACC_TRUNC` and `H5F_ACC_EXCL` are mutually exclusive
  - `H5F_ACC_DEBUG` - print debug information. This flag is used only by HDF5 library developers; it is neither tested nor supported for use in applications.

  For info on file creation in the case of an already-open file, please refer to the Special case section in the C layer Reference Manual at: ../RM_H5F.html::File-Create

H5::H5File::H5File | ( | const H5std_string & | name,
|  | unsigned int | flags,
|  | const FileCreatPropList & | create_plist = `FileCreatPropList::DEFAULT`,
|  | const FileAccPropList & | access_plist = `FileAccPropList::DEFAULT` |
| ) |  |  |

This is another overloaded constructor. It differs from the above constructor only in the type of the name argument.

Parameters:

  | name | - IN: Name of the file - `H5std_string`
  | flags | - IN: File access flags
  | create_plist | - IN: File creation property list, used when modifying default file meta-data. Default to FileCreatPropList::DEFAULT
  | access_plist | - IN: File access property list. Default to FileCreatPropList::DEFAULT

H5::H5File::H5File | ( |  | ) |

Default constructor: creates a stub H5File object.

H5::H5File::H5File | ( | const H5File & | original | ) |

Copy constructor: makes a copy of the original H5File object.

Parameters:

  | original | - IN: H5File instance to copy

H5::H5File::~H5File | ( |  | ) | `[virtual]`

Properly terminates access to this file.

## Member Function Documentation

void H5::H5File::openFile | ( | const H5std_string & | name,
|  | unsigned int | flags,
|  | const FileAccPropList & | access_plist = `FileAccPropList::DEFAULT` |
| ) |  |  |

This is an overloaded member function, provided for convenience. It takes an `H5std_string` for name.

Parameters:

  | name | - IN: Name of the file - `H5std_string`
  | flags | - IN: File access flags
  | access_plist | - IN: File access property list. Default to FileAccPropList::DEFAULT

void H5::H5File::openFile | ( | const char * | name,
|  | unsigned int | flags,
|  | const FileAccPropList & | access_plist = `FileAccPropList::DEFAULT` |
| ) |  |  |

Opens an HDF5 file.

Parameters:

  | name | - IN: Name of the file
  | flags | - IN: File access flags
  | access_plist | - IN: File access property list. Default to FileCreatPropList::DEFAULT

Description
  Valid values of flags include: H5F_ACC_RDWR: Open with read/write access. If the file is currently open for read-only access then it will be reopened. Absence of this flag implies read-only access.

H5F_ACC_RDONLY: Open with read only access. - default

void H5::H5File::close | ( |  | ) | `[virtual]`

Closes this HDF5 file.

Exceptions:

  | H5::FileIException |

void H5::H5File::flush | ( | H5F_scope_t | scope | ) | const

Flushes all buffers associated with a file to disk.

Parameters:

  | scope | - IN: Specifies the scope of the flushing action, which can be either of these values: `H5F_SCOPE_GLOBAL` - Flushes the entire virtual file `H5F_SCOPE_LOCAL` - Flushes only the specified file

Exceptions:

  | H5::FileIException |

FileAccPropList H5::H5File::getAccessPlist | ( |  | ) | const

Returns the access property list of this file.

Returns:
  FileAccPropList object

Exceptions:

  | H5::FileIException |

FileCreatPropList H5::H5File::getCreatePlist | ( |  | ) | const

Returns the creation property list of this file.

Returns:
  FileCreatPropList object

Exceptions:

  | H5::FileIException |

H5std_string H5::H5File::getFileName | ( |  | ) | const

Gets the name of this file.

Returns:
  File name

Exceptions:

  | H5::FileIException |

hsize_t H5::H5File::getFileSize | ( |  | ) | const

Returns the file size of the HDF5 file.

Returns:
  File size

Exceptions:

  | H5::FileIException |

Description
  This function is called after an existing file is opened in order to learn the true size of the underlying file.

hssize_t H5::H5File::getFreeSpace | ( |  | ) | const

Returns the amount of free space in the file.

Returns:
  Amount of free space

Exceptions:

  | H5::FileIException |

ssize_t H5::H5File::getObjCount | ( | unsigned | types | ) | const

Returns the number of opened object IDs (files, datasets, groups and datatypes) in the same file.

Parameters:

  | types | - Type of object to retrieve the count

Returns:
  Number of opened object IDs

Exceptions:

  | H5::FileIException |

Description
  The valid values for types include:
  - `H5F_OBJ_FILE` - Files only
  - `H5F_OBJ_DATASET` - Datasets only
  - `H5F_OBJ_GROUP` - Groups only
  - `H5F_OBJ_DATATYPE` - Named datatypes only
  - `H5F_OBJ_ATTR` - Attributes only
  - `H5F_OBJ_ALL` - All of the above, i.e., `H5F_OBJ_FILE` | `H5F_OBJ_DATASET` | `H5F_OBJ_GROUP` | `H5F_OBJ_DATATYPE` | `H5F_OBJ_ATTR`

  Multiple object types can be combined with the logical OR operator (|).

ssize_t H5::H5File::getObjCount | ( |  | ) | const

This is an overloaded member function, provided for convenience. It takes no parameter and returns the object count of all object types.

Returns:
  Number of opened object IDs

Exceptions:

  | H5::FileIException |

void H5::H5File::getObjIDs | ( | unsigned | types,
|  | size_t | max_objs,
|  | hid_t * | oid_list |
| ) |  |  | const

Retrieves a list of opened object IDs (files, datasets, groups and datatypes) in the same file.

Parameters:

  | types | - Type of object to retrieve the count
  | max_objs | - Maximum number of object identifiers to place into obj_id_list.
  | oid_list | - List of open object identifiers

Exceptions:

  | H5::FileIException |

Description
  The valid values for types include:
  - `H5F_OBJ_FILE` - Files only
  - `H5F_OBJ_DATASET` - Datasets only
  - `H5F_OBJ_GROUP` - Groups only
  - `H5F_OBJ_DATATYPE` - Named datatypes only
  - `H5F_OBJ_ATTR` - Attributes only
  - `H5F_OBJ_ALL` - All of the above, i.e., `H5F_OBJ_FILE` | `H5F_OBJ_DATASET` | `H5F_OBJ_GROUP` | `H5F_OBJ_DATATYPE` | `H5F_OBJ_ATTR`

  Multiple object types can be combined with the logical OR operator (|).

H5G_obj_t H5::H5File::getRefObjType | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  | const

Retrieves the type of object that an object reference points to.

Parameters:

  | ref | - IN: Reference to query
  | ref_type | - IN: Type of reference, valid values are: `H5R_OBJECT` is an object reference. `H5R_DATASET_REGION` is a dataset region reference.

Returns:
  Object type, which can be one of the following:
  - `H5G_LINK` - Object is a symbolic link.
  - `H5G_GROUP` - Object is a group.
  - `H5G_DATASET` - Object is a dataset.
  - `H5G_TYPE` - Object is a named datatype

Exceptions:

  | H5::FileIException |

H5G_obj_t H5::H5File::getObjType | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  | const

This function was misnamed and will be deprecated in favor of H5File::getRefObjType; please use getRefObjType instead.

DataSpace H5::H5File::getRegion | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_DATASET_REGION` |
| ) |  |  | const

Retrieves a dataspace with the region pointed to selected.

Parameters:

  | ref | - IN: Reference to get region of
  | ref_type | - IN: Type of reference to get region of - default

Returns:
  DataSpace instance

Exceptions:

  | H5::FileIException |

void H5::H5File::getVFDHandle | ( | FileAccPropList & | fapl,
|  | void ** | file_handle |
| ) |  |  | const

Returns the pointer to the file handle of the low-level file driver.

Parameters:

  | fapl | - File access property list
  | file_handle | - Pointer to the file handle being used by the low-level virtual file driver

Exceptions:

  | H5::FileIException |

Description
  For the `FAMILY` or `MULTI` drivers, fapl should be defined through the property list functions: `FileAccPropList::setFamilyOffset` for the `FAMILY` driver and `FileAccPropList::setMultiType` for the `MULTI` driver.

The obtained file handle is dynamic and is valid only while the file remains open; it will be invalid if the file is closed and reopened or opened during a subsequent session.

void H5::H5File::getVFDHandle | ( | void ** | file_handle | ) | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  | file_handle | - Pointer to the file handle being used by the low-level virtual file driver

Exceptions:

  | H5::FileIException |

bool H5::H5File::isHdf5 | ( | const char * | name | ) | `[static]`

Determines whether a file in HDF5 format.

Parameters:

  | name | - IN: Name of the file

Returns:
  true if the file is in HDF5 format, and false, otherwise

Exceptions:

  | H5::FileIException |

bool H5::H5File::isHdf5 | ( | const H5std_string & | name | ) | `[static]`

This is an overloaded member function, provided for convenience. It takes an `H5std_string` for name.

Parameters:

  | name | - IN: Name of the file - `H5std_string`

void H5::H5File::reOpen | ( |  | ) |

Reopens this file.

Exceptions:

  | H5::FileIException |

void H5::H5File::reopen | ( |  | ) |

Reopens this file.

Exceptions:

  | H5::FileIException |

Description
  This function will be replaced by the above function `reOpen` in future releases.

void H5::H5File::reference | ( | void * | ref,
|  | const char * | name,
|  | const DataSpace & | dataspace,
|  | H5R_type_t | ref_type = `H5R_DATASET_REGION` |
| ) |  |  | const

Creates a reference to an HDF5 object or a dataset region.

Parameters:

  | ref | - IN: Reference pointer
  | name | - IN: Name of the object to be referenced
  | dataspace | - IN: Dataspace with selection
  | ref_type | - IN: Type of reference to query, valid values are: `H5R_OBJECT` is an object reference. `H5R_DATASET_REGION` is a dataset region reference. - this is the default

Exceptions:

  | H5::IdComponentException |

void H5::H5File::reference | ( | void * | ref,
|  | const char * | name |
| ) |  |  | const

This is an overloaded function, provided for your convenience. It differs from the above function in that it only creates a reference to an HDF5 object, not to a dataset region.

Parameters:

  | ref | - IN: Reference pointer
  | name | - IN: Name of the object to be referenced - `char` pointer

Exceptions:

  | H5::IdComponentException |

Description

void H5::H5File::reference | ( | void * | ref,
|  | const H5std_string & | name |
| ) |  |  | const

This is an overloaded function, provided for your convenience. It differs from the above function in that it takes an `H5std_string` for the object's name.

Parameters:

  | ref | - IN: Reference pointer
  | name | - IN: Name of the object to be referenced - `H5std_string`

virtual H5std_string H5::H5File::fromClass | ( |  | ) | const`[inline, virtual]`

void H5::H5File::throwException | ( | const H5std_string & | func_name,
|  | const H5std_string & | msg |
| ) |  |  | const`[virtual]`

Throws file exception - initially implemented for CommonFG.

Parameters:

  | func_name | - Name of the function where failure occurs
  | msg | - Message describing the failure

Exceptions:

  | H5::FileIException |

Implements H5::CommonFG.

hid_t H5::H5File::getLocId | ( |  | ) | const`[virtual]`

hid_t H5::H5File::getId | ( |  | ) | const`[virtual]`

Implements H5::IdComponent.

Examples:
  h5group.cpp.

void H5::H5File::p_setId | ( | const hid_t | new_id | ) | `[protected, virtual]`

Sets the identifier of this HDF5 file to a new value.

Exceptions:

  | H5::IdComponentException | when the attempt to close the HDF5 object fails