 |
HDF5 2.0.0.258fa78
API Reference
|
|
HDF5 2.0.0.258fa78
API Reference
|
Use the functions in this module to manage identifiers defined by the HDF5 library. See User-defined ID Types for user-defined identifiers and identifier types.
HDF5 identifiers are usually created as a side-effect of creating HDF5 entities such as groups, datasets, attributes, or property lists.
Identifiers defined by the HDF5 library can be used to retrieve information such as path names and reference counts, and their validity can be checked.
Identifiers can be updated by manipulating their reference counts.
Unused identifiers should be reclaimed by closing the associated item, e.g., HDF5 object, or decrementing the reference count to 0.
| Create | Read |
|---|---|
hid_t H5Pcreate(hid_t cls_id) Creates a new property list as an instance of a property list class. | hid_t H5Iget_file_id(hid_t id) Retrieves an identifier for the file containing the specified object. |
| Update | Delete |
Modules | |
| User-defined ID Types | |
Functions | |
| hid_t | H5Iregister_future (H5I_type_t type, const void *object, H5I_future_realize_func_t realize_cb, H5I_future_discard_func_t discard_cb) |
| Registers a "future" object under a type and returns an ID for it. | |
| H5I_type_t | H5Iget_type (hid_t id) |
| Retrieves the type of an object. | |
| hid_t | H5Iget_file_id (hid_t id) |
| Retrieves an identifier for the file containing the specified object. | |
| ssize_t | H5Iget_name (hid_t id, char *name, size_t size) |
| Retrieves a name of an object based on the object identifier. | |
| int | H5Iinc_ref (hid_t id) |
| Increments the reference count for an object. | |
| int | H5Idec_ref (hid_t id) |
| Decrements the reference count for an object. | |
| int | H5Iget_ref (hid_t id) |
| Retrieves the reference count for an object. | |
| htri_t | H5Iis_valid (hid_t id) |
| Determines whether an identifier is valid. | |
| int H5Idec_ref | ( | hid_t | id | ) |
Decrements the reference count for an object.
| [in] | id | Object identifier |
H5Idec_ref() decrements the reference count of the object identified by id.
The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.
The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with H5Iinc_ref(). When an object identifier's reference count reaches zero, the object will be closed. Calling an object identifier's close function decrements the reference count for the identifier, which normally closes the object, but if the reference count for the identifier has been incremented with H5Iinc_ref(), the object will only be closed when the reference count reaches zero with further calls to this function or the object identifier's close function.
If the object ID was created by a collective parallel call (such as H5Dcreate(), H5Gopen(), etc.), the reference count should be modified by all the processes which have copies of the ID. Generally, this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.
This function is of particular value when an application maintains multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that object drops to zero.
Retrieves an identifier for the file containing the specified object.
| [in] | id | Object identifier |
H5Iget_file_id() returns the identifier of the file associated with the object referenced by id.
id is still open, H5Iget_file_id() will retrieve the existing file identifier. If there is no existing file identifier for the file, i.e., the file has been closed, H5Iget_file_id() will reopen the file and return a new file identifier. In either case, the file identifier must eventually be released using H5Fclose().Retrieves a name of an object based on the object identifier.
| [in] | id | Object identifier |
| [out] | name | A buffer for the name associated with the identifier |
| [in] | size | The size, in bytes, of the name buffer. Must be the size of the object name in bytes plus 1 for a NULL terminator |
H5Iget_name() retrieves a name for the object identified by id.
Up to size characters of the name are returned in name; additional characters, if any, are not returned to the user application.
Up to size characters of the object name are returned in name; additional characters, if any, are not returned to the user application.
If the length of the object name, which determines the required value of size, is unknown, a preliminary call to H5Iget_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the object name. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Iget_name() call, which will retrieve the actual object name.
If the object identified by id is an attribute, as determined via H5Iget_type(), H5Iget_name() retrieves the name of the object to which that attribute is attached. To retrieve the name of the attribute itself, use H5Aget_name().
If there is no name associated with the object identifier or if the name is NULL, H5Iget_name() returns 0 (zero).
| int H5Iget_ref | ( | hid_t | id | ) |
Retrieves the reference count for an object.
| [in] | id | Object identifier |
H5Iget_ref() retrieves the reference count of the object identified by id.
The reference count for an object identifier is attached to the information about an object in memory and has no relation to the number of links to an object on disk.
The function H5Iis_valid() is used to determine whether a specific object identifier is valid.
| H5I_type_t H5Iget_type | ( | hid_t | id | ) |
Retrieves the type of an object.
| [in] | id | Object identifier |
H5Iget_type() retrieves the type of the object identified by id. If no valid type can be determined or the identifier submitted is invalid, the function returns H5I_BADID.
This function is of particular use in determining the type of object closing function (H5Dclose(), H5Gclose(), etc.) to call after a call to H5Rdereference().
id would identify if it were valid; it does not determine whether id is valid identifier. Validity can be determined with a call to H5Iis_valid().| int H5Iinc_ref | ( | hid_t | id | ) |
Increments the reference count for an object.
| [in] | id | Object identifier |
H5Iinc_ref() increments the reference count of the object identified by id.
The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.
The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with H5Idec_ref(). When an object ID's reference count reaches zero, the object will be closed. Calling an object ID's close function decrements the reference count for the ID which normally closes the object, but if the reference count for the ID has been incremented with this function, the object will only be closed when the reference count reaches zero with further calls to H5Idec_ref() or the object ID's close function.
If the object ID was created by a collective parallel call (such as H5Dcreate(), H5Gopen(), etc.), the reference count should be modified by all the processes which have copies of the ID. Generally this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.
This function is of particular value when an application is maintaining multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that that object drops to zero.
Determines whether an identifier is valid.
| [in] | id | Object identifier |
H5Iis_valid() determines whether the identifier id is valid.
Valid identifiers are those that have been obtained by an application and can still be used to access the original target. Examples of invalid identifiers include:
H5Iis_valid() can be used with any type of identifier: object identifier, property list identifier, attribute identifier, error message identifier, etc. When necessary, a call to H5Iget_type() can determine the type of object that the id identifies.
| hid_t H5Iregister_future | ( | H5I_type_t | type, |
| const void * | object, | ||
| H5I_future_realize_func_t | realize_cb, | ||
| H5I_future_discard_func_t | discard_cb | ||
| ) |
Registers a "future" object under a type and returns an ID for it.
| [in] | type | The identifier of the type of the new ID |
| [in] | object | Pointer to "future" object for which a new ID is created |
| [in] | realize_cb | Function pointer to realize a future object |
| [in] | discard_cb | Function pointer to destroy a future object |
H5Iregister_future() creates and returns a new ID for a "future" object. Future objects are a special kind of object and represent a placeholder for an object that has not yet been created or opened. The realize_cb will be invoked by the HDF5 library to 'realize' the future object as an actual object. A call to H5Iobject_verify() will invoke the realize_cb callback and if it successfully returns, will return the actual object, not the future object.
The type parameter is the identifier for the ID type to which this new future ID will belong. This identifier may have been created by a call to H5Iregister_type() or may be one of the HDF5 pre-defined ID classes (e.g. H5I_FILE, H5I_GROUP, H5I_DATASPACE, etc).
The object parameter is a pointer to the memory which the new ID will be a reference to. This pointer will be stored by the library, but will not be returned to a call to H5Iobject_verify() until the realize_cb callback has returned the actual pointer for the object.
A NULL value for object is allowed.
The realize_cb parameter is a function pointer that will be invoked by the HDF5 library to convert a future object into an actual object. The realize_cb function may be invoked by H5Iobject_verify() to return the actual object for a user-defined ID class (i.e. an ID class registered with H5Iregister_type()) or internally by the HDF5 library in order to use or get information from an HDF5 pre-defined ID type. For example, the realize_cb for a future dataspace object will be called during the process of returning information from H5Sget_simple_extent_dims().
Note that although the realize_cb routine returns an ID (as a parameter) for the actual object, the HDF5 library will swap the actual object in that ID for the future object in the future ID. This ensures that the ID value for the object doesn't change for the user when the object is realized.
Note that the realize_cb callback could receive a NULL value for a future object pointer, if one was used when H5Iregister_future() was initially called. This is permitted as a means of allowing the realize_cb to act as a generator of new objects, without requiring creation of unnecessary future objects.
It is an error to pass NULL for realize_cb.
The discard_cb parameter is a function pointer that will be invoked by the HDF5 library to destroy a future object. This callback will always be invoked for every future object, whether the realize_cb is invoked on it or not. It's possible that the discard_cb is invoked on a future object without the realize_cb being invoked, e.g. when a future ID is closed without requiring the future object to be realized into an actual one.
Note that the discard_cb callback could receive a NULL value for a future object pointer, if one was used when H5Iregister_future() was initially called.
It is an error to pass NULL for discard_cb.
1.9.7