HDF5 C++ API Reference Manual

 

 

 

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

---