Reference Manual Changes Related to

the New File Close Feature

By Raymond Lu

Dec 18, 2001

Name: H5Fget_obj_count

Signature:

herr_t H5Fget_obj_count(hid_t file_id, unsigned types, unsigned* obj_id_count)

Purpose:

Return object ID count for opened file(s).

Description:

Given a file ID and object types, H5Fget_obj_count returns the number of the object IDs opened in current HDF5 application program; given the value H5F_OBJ_ALL as the file_id, this function returns the number of the opened object IDs of “types” in all currently opened files in this HDF5 application program. “types” value can be combined with bit-wise OR operator (`|’).

Parameter:

hid_t file_id

IN: (One of) the file ID of an open file. Use H5F_OBJ_ALL to retrieve objects in all opened files in current HDF5 application program.

unsigned types

IN: Object type. Allowable values are

H5F_OBJ_FILE for files,

H5F_OBJ_DATASET for datasets,

H5F_OBJ_GROUP for groups,

H5F_OBJ_DATATYPE for named datatypes,

H5F_OBJ_ALL for all types above.

unsigned* obj_id_count

OUT: Pointer to the location to return the number of the opened object IDs in file(s).

Returns:

Returns non-negative value if successful; otherwise returns a negative value.

Name: H5Fget_obj_ids

Signature:

herr_t H5Fget_obj_ids(hid_t file_id, unsigned types, hid_t* obj_id_list)

Purpose:

Returns a list of the opened object IDs.

Description:

Given a file ID for an opened file and object types, H5Fget_obj_ids returns a list of opened object IDs in current HDF5 application program; given the value H5F_OBJ_ALL as the file_id, this function returns a list of opened object IDs of “types” in all currently opened files in this HDF5 application program. “types” value can be combined with bit-wise Or operator(`|’).

Parameters:

hid_t file_id

IN: (One of) the file ID for an open file. Use H5F_OBJ_ALL to retrieve objects in all opened files in current HDF5 application files.

unsigned types

IN: Object type. Allowable values are

H5F_OBJ_FILE for files,

H5F_OBJ_DATASET for datasets,

H5F_OBJ_GROUP for groups,

H5F_OBJ_DATATYPE for datatypes,

H5F_OBJ_ALL for all types above.

hid_t* obj_id_list

OUT: Pointer to the location to return a list of opened object IDs in the file

Returns:

Returns non-negative value if successful; otherwise returns a negative value.

Name: H5Pget_fclose_degree

Signature:

herr_t H5Pget_fclose_degree(hid_t plist_id, H5F_close_degree_t* fc_degree)

Purpose:

Returns the file close degree property.

Description:

H5Pget_fclose_degree returns the file close degree property in a file access property list. This property determines how H5Fclose deals with opened object IDs for a file. It has four values:

	H5Fclose behavior with no opened object in file	H5Fclose behavior with objects opened in file
H5F_CLOSE_WEAK	Actual file is closed.	File ID is closed but actual file close is delayed until all objects are closed.
H5F_CLOSE_SEMI	Actual file is closed.	Returns failure while file ID remains valid.
H5F_CLOSE_STRONG	Actual file is closed.	Close all opened objects first, then file is closed.
H5F_CLOSE_DEFAULT	The VFL driver chooses the behavior. Currently, all the VFL drivers set this property to H5F_CLOSE_WEAK, except for the MPI-I/O driver, which is H5F_CLOSE_SEMI.

(Assume there is only one file ID left for all above behavior. Please refer to the descriptions of H5Fclose, H5Fopen, and H5Fcreate.)

Parameters:

hid_t plist_id

IN: File access property list ID for query.

H5F_close_degree_t* fc_degree

OUT: Pointer to a location to return the file close degree property.

Returns:

Non-negative value if successful; otherwise returns a negative value.

Name: H5Pset_fclose_degree

Signature:

herr_t H5Pset_fclose_degree(hid_t plist_id, H5F_close_degree_t fc_degree)

Purpose:

Sets the file close degree property.

Description:

H5Pset_fclose_degree sets the file close degree property in a file access property list. This property determines how H5Fclose deals with opened object IDs for a file. It has four values:

	H5Fclose behavior with no opened object in file	H5Fclose behavior with objects opened in file
H5F_CLOSE_WEAK	Actual file is closed.	File ID is closed but actual file close is delayed until all objects are closed.
H5F_CLOSE_SEMI	Actual file is closed.	Returns failure.
H5F_CLOSE_STRONG	Actual file is closed.	Close all opened objects first, then file is closed.
H5F_CLOSE_DEFAULT	The VFL driver chooses the behavior. Currently, all the VFL drivers set this property to H5F_CLOSE_WEAK, except for the MPI-I/O driver, which is H5F_CLOSE_SEMI.

(Assume there is only one file ID left for all above behavior.)

Parameters:

hid_t plist_id

IN: File access property list ID for query.

H5F_close_degree_t fc_degree

IN: The value of file close degree property.

Returns:

Non-negative value if successful; otherwise returns a negative value.

Name: H5Fopen

Signature:

hid_t H5Fopen(const char *name, unsigned flags, hid_t fapl_id)

Purpose:

Open an existing file

Description:

H5Fopen opens an existing file and is the primary function for accessing existing HDF5 files. The parameter fapl_id is a file access property list identifier or H5P_DEFAULT for the default I/O access parameters.

The flags argument determines whether writing to an existing file will be allowed or not. The file is opened with read and write permission if flags is set to H5F_ACC_RDWR. All flags may be combined with the bit-wise OR operator (`|') to change the behavior of the file open call, subject to the conditions described below under “parameters”. The more complex behaviors of a file's access are controlled through the file-access property list.

A file which is opened more than once without closing first will return a unique file ID and can be accessed through all of them. All the open and create calls for the same file should use the file access property list with the same file close degree property(please refer to functions H5Pget_fclose_degree and H5Pset_fclose_degree for details).

The return value is a file identifier for the open file and it should be closed by calling H5Fclose() when it is no longer needed.

Parameters:

const char *name

Name of the file to access

unsigned flags

File access flags. Allowable values are:

H5F_ACC_RDWR

Allow read and write access to file.

H5F_ACC_RDONLY

Allow read-only access to file.

H5F_ACC_DEBUG

Prints debug information. This flag is used only by HDF5 library developers; it is neither tested nor supported for use in applications.

H5F_ACC_RDWR and H5F_ACC_RDONLY are mutually exclusive; use exactly one.

hid_t fapl_id

Identifier for the file access properties list. If parallel file access is desired, this is a collective call according to the communicator stored in the access_id. Use H5P_DEFAULT for default file access properties.

Returns:

Returns a file ID if successful; otherwise returns a negative value.

Name: H5Fcreate

Signature:

hid_t H5Fcreate(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id)

Purpose:

Creates a HDF5 file

Description:

H5Fcreate is the primary function for creating HDF5 files .

The flags parameter determines whether an existing file will be overwritten. All newly created files are opened for both reading and writing. All flags may be combined with the bit-wise OR operator (`|') to change the behavior of the H5Fcreate call, subject to the conditions described below in “parameters”.

The more complex behaviors of file creation and access are controlled through the file-creation and file-access property lists. The value of H5P_DEFAULT for a property list value indicates that the library should use the default values for the appropriate property list.

A file which is opened more than once without closing first will return a unique file ID and can be accessed through all of them. All the open and create calls for the same file should use the file access property list with the same file close degree property(please refer to functions H5Pget_fclose_degree and H5Pset_fclose_degree for details).

The return value is a file identifier for the created file and it should be closed by calling H5Fclose() when it is no longer needed.

Parameters:

const char *name

Name of the file to access

unsigned flags

File access flags. Allowable values are:

H5F_ACC_RDWR

Allow read and write access to file.

H5F_ACC_RDONLY

Allow read-only access to file.

H5F_ACC_DEBUG

Prints debug information. This flag is used only by HDF5 library developers; it is neither tested nor supported for use in applications.

H5F_ACC_RDWR and H5F_ACC_RDONLY are mutually exclusive; use exactly one.

hid_t fapl_id

Identifier for the file access properties list. If parallel file access is desired, this is a collective call according to the communicator stored in the access_id. Use H5P_DEFAULT for default file access properties.

Returns:

Returns a file ID if successful; otherwise returns a negative value.

Name: H5Fclose

Signature:

herr_t H5Fclose(hid_t file_id)

Purpose:

Terminates access to an HDF5 file.

Description:

H5Fclose terminates access to an HDF5 file by flushing all data to storage and terminating access to the file through file_id.

This function behaves in several different ways according the file close degree property in file access property list(set by H5Pset_fclose_degree function, please refer to functions H5Pget_fclose_degree and H5Pset_fclose_degree for details ).

Parameters:

hid_t file_id

ID of a file to be terminated.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Last revision: Raymond Lu; Dec 18, 2001

Email: hdf5lib@ncsa.uiuc.edu