![]() |
HDF5
1.8.23
C-API Reference
|
#include "H5public.h"
Macros | |
#define | H5_SIZEOF_HID_T H5_SIZEOF_INT |
#define | H5I_INVALID_HID (-1) |
Typedefs | |
typedef int | hid_t |
typedef herr_t(* | H5I_free_t) (void *) |
typedef int(* | H5I_search_func_t) (void *obj, hid_t id, void *key) |
Enumerations | |
enum | H5I_type_t { H5I_UNINIT = (-2) , H5I_BADID = (-1) , H5I_FILE = 1 , H5I_GROUP , H5I_DATATYPE , H5I_DATASPACE , H5I_DATASET , H5I_ATTR , H5I_REFERENCE , H5I_VFL , H5I_GENPROP_CLS , H5I_GENPROP_LST , H5I_ERROR_CLASS , H5I_ERROR_MSG , H5I_ERROR_STACK , H5I_NTYPES } |
Functions | |
hid_t | H5Iregister (H5I_type_t type, const void *object) |
Registers an object under a type and returns an ID for it. More... | |
void * | H5Iobject_verify (hid_t id, H5I_type_t type) |
Returns the object referenced by an ID. More... | |
void * | H5Iremove_verify (hid_t id, H5I_type_t type) |
Removes an ID from its type. More... | |
H5I_type_t | H5Iget_type (hid_t id) |
Retrieves the type of an object. More... | |
hid_t | H5Iget_file_id (hid_t id) |
Retrieves an identifier for the file containing the specified object. More... | |
ssize_t | H5Iget_name (hid_t id, char *name, size_t size) |
Retrieves a name of an object based on the object identifier. More... | |
int | H5Iinc_ref (hid_t id) |
Increments the reference count for an object. More... | |
int | H5Idec_ref (hid_t id) |
Decrements the reference count for an object. More... | |
int | H5Iget_ref (hid_t id) |
Retrieves the reference count for an object. More... | |
H5I_type_t | H5Iregister_type (size_t hash_size, unsigned reserved, H5I_free_t free_func) |
Creates and returns a new ID type. More... | |
herr_t | H5Iclear_type (H5I_type_t type, hbool_t force) |
Deletes all identifiers of the given type. More... | |
herr_t | H5Idestroy_type (H5I_type_t type) |
Removes an identifier type and all identifiers within that type. More... | |
int | H5Iinc_type_ref (H5I_type_t type) |
Increments the reference count on an ID type. More... | |
int | H5Idec_type_ref (H5I_type_t type) |
Decrements the reference count on an identifier type. More... | |
int | H5Iget_type_ref (H5I_type_t type) |
Retrieves the reference count on an ID type. More... | |
void * | H5Isearch (H5I_type_t type, H5I_search_func_t func, void *key) |
Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied. More... | |
herr_t | H5Inmembers (H5I_type_t type, hsize_t *num_members) |
Returns the number of identifiers in a given identifier type. More... | |
htri_t | H5Itype_exists (H5I_type_t type) |
Determines whether an identifier type is registered. More... | |
htri_t | H5Iis_valid (hid_t id) |
Determines whether an identifier is valid. More... | |
#define H5_SIZEOF_HID_T H5_SIZEOF_INT |
#define H5I_INVALID_HID (-1) |
An invalid object ID. This is also negative for error return.
typedef herr_t(* H5I_free_t) (void *) |
A function for freeing objects. This function will be called with an object ID type number and a pointer to the object. The function should free the object and return non-negative to indicate that the object can be removed from the ID type. If the function returns negative (failure) then the object will remain in the ID type.
typedef int(* H5I_search_func_t) (void *obj, hid_t id, void *key) |
The type of a function to compare objects & keys
typedef int hid_t |
Type of atoms to return to users
enum H5I_type_t |
Library type values.
herr_t H5Iclear_type | ( | H5I_type_t | type, |
hbool_t | force | ||
) |
Deletes all identifiers of the given type.
[in] | type | Identifier of identifier type which is to be cleared of identifiers |
[in] | force | Whether or not to force deletion of all identifiers |
H5Iclear_type() deletes all identifiers of the type identified by the argument type
.
The identifier type's free function is first called on all of these identifiers to free their memory, then they are removed from the type.
If the force
flag is set to false, only those identifiers whose reference counts are equal to 1 will be deleted, and all other identifiers will be entirely unchanged. If the force flag is true, all identifiers of this type will be deleted.
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 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.
int H5Idec_type_ref | ( | H5I_type_t | type | ) |
Decrements the reference count on an identifier type.
[in] | type | The identifier of the type whose reference count is to be decremented |
H5Idec_type_ref() decrements the reference count on an identifier type. The reference count is used by the library to indicate when an identifier type can be destroyed. If the reference count reaches zero, this function will destroy it.
The type parameter is the identifier for the identifier type whose reference count is to be decremented. This identifier must have been created by a call to H5Iregister_type().
herr_t H5Idestroy_type | ( | H5I_type_t | type | ) |
Removes an identifier type and all identifiers within that type.
[in] | type | Identifier of identifier type which is to be destroyed |
H5Idestroy_type deletes an entire identifier type type
. All identifiers of this type are destroyed and no new identifiers of this type can be registered.
The type’s free function is called on all of the identifiers which are deleted by this function, freeing their memory. In addition, all memory used by this type’s hash table is freed.
Since the H5I_type_t values of destroyed identifier types are reused when new types are registered, it is a good idea to set the variable holding the value of the destroyed type to H5I_UNINIT.
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().ssize_t H5Iget_name | ( | hid_t | id, |
char * | name, | ||
size_t | size | ||
) |
Retrieves a name of an object based on the object identifier.
[in] | id | Object identifier |
[out] | name | A buffer for thename associated with the identifier |
[in] | size | The size of the name buffer; usually the size of the 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.
If the length of the name, which determines the required value of size
, is unknown, a preliminary H5Iget_name() call 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, is then assigned to size for a second H5Iget_name() call, which will retrieve the actual 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 H5Iget_type_ref | ( | H5I_type_t | type | ) |
Retrieves the reference count on an ID type.
[in] | type | The identifier of the type whose reference count is to be retrieved |
H5Iget_type_ref() retrieves the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.
The type parameter is the identifier for the ID type whose reference count is to be retrieved. This identifier must have been created by a call to H5Iregister_type().
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.
int H5Iinc_type_ref | ( | H5I_type_t | type | ) |
Increments the reference count on an ID type.
[in] | type | The identifier of the type whose reference count is to be incremented |
H5Iinc_type_ref() increments the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.
The type parameter is the identifier for the ID type whose reference count is to be incremented. This identifier must have been created by a call to H5Iregister_type().
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 the object that id
identifies.
herr_t H5Inmembers | ( | H5I_type_t | type, |
hsize_t * | num_members | ||
) |
Returns the number of identifiers in a given identifier type.
[in] | type | The identifier type |
[out] | num_members | Number of identifiers of the specified identifier type |
H5Inmembers() returns the number of identifiers of the identifier type specified in type
.
The number of identifiers is returned in num_members
. If no identifiers of this type have been registered, the type does not exist, or it has been destroyed, num_members
is returned with the value 0.
void * H5Iobject_verify | ( | hid_t | id, |
H5I_type_t | type | ||
) |
Returns the object referenced by an ID.
[in] | id | ID to be dereferenced |
[in] | type | The identifier type |
id
on success, NULL on failure.H5Iobject_verify() returns a pointer to the memory referenced by id after verifying that id
is of type type
. This function is analogous to dereferencing a pointer in C with type checking.
hid_t H5Iregister | ( | H5I_type_t | type, |
const void * | object | ||
) |
Registers an 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 object for which a new ID is created |
H5Iregister() creates and returns a new ID for an object.
The type
parameter is the identifier for the ID type to which this new ID will belong. This identifier must have been created by a call to H5Iregister_type().
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 and returned via a call to H5Iobject_verify().
H5I_type_t H5Iregister_type | ( | size_t | hash_size, |
unsigned | reserved, | ||
H5I_free_t | free_func | ||
) |
Creates and returns a new ID type.
[in] | hash_size | Minimum hash table size (in entries) used to store IDs for the new type |
[in] | reserved | Number of reserved IDs for the new type |
[in] | free_func | Function used to deallocate space for a single ID |
H5Iregister_type() allocates space for a new ID type and returns an identifier for it.
The hash_size
parameter indicates the minimum size of the hash table used to store IDs in the new type.
The reserved
parameter indicates the number of IDs in this new type to be reserved. Reserved IDs are valid IDs which are not associated with any storage within the library.
The free_func
parameter is a function pointer to a function which returns an herr_t and accepts a void*
. The purpose of this function is to deallocate memory for a single ID. It will be called by H5Iclear_type() and H5Idestroy_type() on each ID. This function is NOT called by H5Iremove_verify(). The void*
will be the same pointer which was passed in to the H5Iregister() function. The free_func
function should return 0 on success and -1 on failure.
void * H5Iremove_verify | ( | hid_t | id, |
H5I_type_t | type | ||
) |
Removes an ID from its type.
[in] | id | The ID to be removed from its type |
[in] | type | The identifier type |
id
on success, NULL on failure.H5Iremove_verify() first ensures that id
belongs to type
. If so, it removes id
from its type and returns the pointer to the memory it referred to. This pointer is the same pointer that was placed in storage by H5Iregister(). If id does not belong to type
, then NULL is returned.
The id
parameter is the ID which is to be removed from its type.
The type
parameter is the identifier for the ID type which id
is supposed to belong to. This identifier must have been created by a call to H5Iregister_type().
id
refers to. The pointer returned by H5Iregister() must be deallocated by the user to avoid memory leaks. void * H5Isearch | ( | H5I_type_t | type, |
H5I_search_func_t | func, | ||
void * | key | ||
) |
Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied.
[in] | type | The identifier of the type to be searched |
[in] | func | The function defining the search criteria |
[in] | key | A key for the search function |
H5Isearch() searches through a given ID type to find an object that satisfies the criteria defined by func
. If such an object is found, the pointer to the memory containing this object is returned. Otherwise, NULL is returned. To do this, func
is called on every member of type type
. The first member to satisfy func
is returned.
The type
parameter is the identifier for the ID type which is to be searched. This identifier must have been created by a call to H5Iregister_type().
The parameter func
is a function pointer to a function which takes three parameters. The first parameter is a void*
and will be a pointer to the object to be tested. This is the same object that was placed in storage using H5Iregister(). The second parameter is a hid_t and is the ID of the object to be tested. The last parameter is a void*
. This is the key
parameter and can be used however the user finds helpful, or it can be ignored if it is not needed. func
returns 0 if the object it is testing does not pass its criteria. A non-zero value should be returned if the object does pass its criteria. H5I_search_func_t is defined in H5Ipublic.h and is shown below.
The key
parameter will be passed to the search function as a parameter. It can be used to further define the search at run-time.
htri_t H5Itype_exists | ( | H5I_type_t | type | ) |
Determines whether an identifier type is registered.
[in] | type | Identifier type |
H5Itype_exists() determines whether the given identifier type, type
, is registered with the library.