 |
HDF5
1.12.1
|
|
|
HDF5
1.12.1
|
|
Use the functions in this module to manage HDF5 attributes.
The Attribute Interface, H5A, provides a mechanism for attaching additional information to a dataset, group, or named datatype.
Attributes are accessed by opening the object that they are attached to and are not independent objects. Typically an attribute is small in size and contains user metadata about the object that it is attached to.
Attributes look similar to HDF5 datasets in that they have a datatype and dataspace. However, they do not support partial I/O operations and cannot be compressed or extended.
| Create | Read |
|---|---|
{
__label__ fail_acpl, fail_attr, fail_file;
hid_t file, acpl, fspace, attr;
unsigned mode = H5F_ACC_TRUNC;
char file_name[] = "f1.h5";
// attribute names can be arbitrary Unicode strings
char attr_name[] = "Χαρακτηριστικό";
ret_val = EXIT_FAILURE;
goto fail_file;
}
ret_val = EXIT_FAILURE;
goto fail_acpl;
}
// use UTF-8 encoding for the attribute name
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a scalar (singleton) attribute
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create an attribute on the root group
ret_val = EXIT_FAILURE;
goto fail_attr;
}
H5Aclose(attr);
fail_attr:
H5Sclose(fspace);
fail_fspace:
H5Pclose(acpl);
fail_acpl:
H5Fclose(file);
fail_file:;
}
| {
__label__ fail_attr, fail_file;
hid_t file, attr;
unsigned mode = H5F_ACC_RDONLY;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
int value;
ret_val = EXIT_FAILURE;
goto fail_file;
}
ret_val = EXIT_FAILURE;
goto fail_attr;
}
// read the attribute value
ret_val = EXIT_FAILURE;
// do something w/ the attribute value
H5Aclose(attr);
fail_attr:
H5Fclose(file);
fail_file:;
}
|
| Update | Delete |
{
__label__ fail_attr, fail_file;
hid_t file, attr;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
int value = 1234;
ret_val = EXIT_FAILURE;
goto fail_file;
}
ret_val = EXIT_FAILURE;
goto fail_attr;
}
// update the attribute value
ret_val = EXIT_FAILURE;
H5Aclose(attr);
fail_attr:
H5Fclose(file);
fail_file:;
}
| {
__label__ fail_attr, fail_file;
hid_t file;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
ret_val = EXIT_FAILURE;
goto fail_file;
}
// delete the attribute
if (H5Adelete(file, attr_name) < 0) {
ret_val = EXIT_FAILURE;
goto fail_attr;
}
fail_attr:
H5Fclose(file);
fail_file:;
}
|
Macros | |
| #define | H5Acreate H5Acreate2 |
| #define | H5Aiterate H5Aiterate2 |
Functions | |
| herr_t | H5Aclose (hid_t attr_id) |
| Closes the specified attribute. More... | |
| hid_t | H5Acreate2 (hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id) |
| Creates an attribute attached to a specified object. More... | |
| hid_t | H5Acreate_by_name (hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id) |
| Creates an attribute attached to a specified object. More... | |
| herr_t | H5Adelete (hid_t loc_id, const char *attr_name) |
| Deletes an attribute from a specified location. More... | |
| herr_t | H5Adelete_by_idx (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id) |
| Deletes an attribute from an object according to index order. More... | |
| herr_t | H5Adelete_by_name (hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id) |
| Removes an attribute from a specified location. More... | |
| htri_t | H5Aexists (hid_t obj_id, const char *attr_name) |
| Determines whether an attribute with a given name exists on an object. More... | |
| htri_t | H5Aexists_by_name (hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id) |
| Determines whether an attribute with a given name exists on an object. More... | |
| hid_t | H5Aget_create_plist (hid_t attr_id) |
| Gets an attribute creation property list identifier. More... | |
| herr_t | H5Aget_info (hid_t attr_id, H5A_info_t *ainfo) |
| Retrieves attribute information, by attribute identifier. More... | |
| herr_t | H5Aget_info_by_idx (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo, hid_t lapl_id) |
| Retrieves attribute information by attribute index position. More... | |
| herr_t | H5Aget_info_by_name (hid_t loc_id, const char *obj_name, const char *attr_name, H5A_info_t *ainfo, hid_t lapl_id) |
| Retrieves attribute information, by attribute name. More... | |
| ssize_t | H5Aget_name (hid_t attr_id, size_t buf_size, char *buf) |
| Gets an attribute name. More... | |
| ssize_t | H5Aget_name_by_idx (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id) |
| Gets an attribute name, by attribute index position. More... | |
| hid_t | H5Aget_space (hid_t attr_id) |
| Gets a copy of the dataspace for an attribute. More... | |
| hsize_t | H5Aget_storage_size (hid_t attr_id) |
| Returns the amount of storage required for an attribute. More... | |
| hid_t | H5Aget_type (hid_t attr_id) |
| Gets an attribute datatype. More... | |
| herr_t | H5Aiterate2 (hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data) |
| Calls user-defined function for each attribute on an object. More... | |
| herr_t | H5Aiterate_by_name (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, hid_t lapl_id) |
| Calls user-defined function for each attribute on an object. More... | |
| hid_t | H5Aopen (hid_t obj_id, const char *attr_name, hid_t aapl_id) |
| Opens an attribute for an object specified by object identifier and attribute name. More... | |
| hid_t | H5Aopen_by_idx (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id) |
| Opens the nth attribute attached to an object. More... | |
| hid_t | H5Aopen_by_name (hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, hid_t lapl_id) |
| Opens an attribute for an object by object name and attribute name. More... | |
| herr_t | H5Aread (hid_t attr_id, hid_t type_id, void *buf) |
| Reads the value of an attribute. More... | |
| herr_t | H5Arename (hid_t loc_id, const char *old_name, const char *new_name) |
| Renames an attribute. More... | |
| herr_t | H5Awrite (hid_t attr_id, hid_t type_id, const void *buf) |
| Writes data to an attribute. More... | |
| herr_t | H5Arename_by_name (hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id) |
| hid_t | H5Acreate1 (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id) |
| Creates an attribute attached to a specified object. More... | |
| int | H5Aget_num_attrs (hid_t loc_id) |
| Determines the number of attributes attached to an object. More... | |
| herr_t | H5Aiterate1 (hid_t loc_id, unsigned *idx, H5A_operator1_t op, void *op_data) |
| Calls a user’s function for each attribute on an object. More... | |
| hid_t | H5Aopen_idx (hid_t loc_id, unsigned idx) |
| Opens the attribute specified by its index. More... | |
| hid_t | H5Aopen_name (hid_t loc_id, const char *name) |
| Opens an attribute specified by name. More... | |
| #define H5Acreate H5Acreate2 |
H5Acreate() is a macro that is mapped to either H5Acreate1() or H5Acreate2().
| #define H5Aiterate H5Aiterate2 |
H5Aiterate() is a macro that is mapped to either H5Aiterate1() or H5Aiterate2().
Closes the specified attribute.
| [in] | attr_id | Attribute identifier |
H5Aclose() terminates access to the attribute specified by attr_id by releasing the identifier.
Creates an attribute attached to a specified object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | name | Name of attribute to locate and open |
| [in] | type_id | Identifier of attribute datatype |
| [in] | space_id | Dataspace identifier |
| [in] | acpl_id | Attribute creation property list identifier |
acpl parameters is currently not used; specify H5P_DEFAULT.H5Acreate1() creates an attribute, name, which is attached to the object specified by the identifier loc_id.
The attribute name, name, must be unique for the object.
The attribute is created with the specified datatype and dataspace, type_id and space_id, which are created with the H5T and H5S interfaces, respectively.
If type_id is either a fixed-length or variable-length string, it is important to set the string length when defining the datatype. String datatypes are derived from H5T_C_S1 (or H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in size. See H5Tset_size() and Creating variable-length string datatypes.
The attribute identifier returned by this function must be released with H5Aclose() resource leaks will develop.
| hid_t H5Acreate2 | ( | hid_t | loc_id, |
| const char * | attr_name, | ||
| hid_t | type_id, | ||
| hid_t | space_id, | ||
| hid_t | acpl_id, | ||
| hid_t | aapl_id | ||
| ) |
Creates an attribute attached to a specified object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | attr_name | Name of attribute |
| [in] | type_id | Attribute datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | acpl_id | Attribute creation property list identifier |
| [in] | aapl_id | Attribute access property list identifier |
H5Acreate2() creates an attribute, attr_name, which is attached to the object specified by the identifier loc_id.
The attribute name, attr_name, must be unique for the object.
The attribute is created with the specified datatype and dataspace, type_id and space_id, which are created with the H5T and H5S interfaces, respectively.
If type_id is either a fixed-length or variable-length string, it is important to set the string length when defining the datatype. String datatypes are derived from H5T_C_S1 (or H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in size. See H5Tset_size() and Creating variable-length string datatypes.
The access property list is currently unused, but will be used in the future. This property list should currently be H5P_DEFAULT.
The attribute identifier returned by this function must be released with H5Aclose() resource leaks will develop.
aapl parameter is currently not used; specify H5P_DEFAULT.loc_id is a file identifier, the attribute will be attached that file’s root group.| hid_t H5Acreate_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| const char * | attr_name, | ||
| hid_t | type_id, | ||
| hid_t | space_id, | ||
| hid_t | acpl_id, | ||
| hid_t | aapl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates an attribute attached to a specified object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name, relative to loc_id, of object that attribute is to be attached to |
| [in] | attr_name | Attribute name |
| [in] | type_id | Attribute datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | acpl_id | Attribute creation property list identifier |
| [in] | aapl_id | Attribute access property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Acreate_by_name() creates an attribute, attr_name, which is attached to the object specified by loc_id and obj_name.
loc_id is a location identifier; obj_name is the object name relative to loc_id. If loc_id fully specifies the object to which the attribute is to be attached, obj_name should be '.' (a dot).
The attribute name, attr_name, must be unique for the object.
The attribute is created with the specified datatype and dataspace, type_id and space_id, which are created with the H5T and H5S interfaces respectively.
The attribute creation and access property lists are currently unused, but will be used in the future for optional attribute creation and access properties. These property lists should currently be H5P_DEFAULT.
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
The attribute identifier returned by this function must be released with H5close() or resource leaks will develop.
Deletes an attribute from a specified location.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | attr_name | Name of the attribute to delete |
H5Adelete() removes the attribute specified by its name, attr_name, from a file, dataset, group, or named datatype. This function should not be used when attribute identifiers are open on loc_id as it may cause the internal indexes of the attributes to change and future writes to the open attributes to produce incorrect results.
| herr_t H5Adelete_by_idx | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| hid_t | lapl_id | ||
| ) |
Deletes an attribute from an object according to index order.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object, relative to location, from which attribute is to be removed |
| [in] | idx_type | Type of index |
| [in] | order | Order in which to iterate over index |
| [in] | n | Offset within index |
| [in] | lapl_id | Link access property list identifier |
H5Adelete_by_idx() removes an attribute, specified by its location in an index, from an object.
The object from which the attribute is to be removed is specified by a location identifier and name, loc_id and obj_name, respectively. If loc_id fully specifies the object from which the attribute is to be removed, obj_name should be '.' (a dot).
The attribute to be removed is specified by a position in an index, n. The type of index is specified by idx_type and may be H5_INDEX_NAME, for an alpha-numeric index by name, or H5_INDEX_CRT_ORDER, for an index by creation order. The order in which the index is to be traversed is specified by order and may be H5_ITER_INC (increment) for top-down iteration, H5_ITER_DEC (decrement) for bottom-up iteration, or H5_ITER_NATIVE, in which case HDF5 will iterate in the fastest-available order. For example, if idx_type, order, and n are set to H5_INDEX_NAME, H5_ITER_INC, and 5, respectively, the fifth attribute by alpha-numeric order of attribute names will be removed.
For a discussion of idx_type and order, the valid values of those parameters, and the use of n, see the description of H5Aiterate2().
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
| herr_t H5Adelete_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| const char * | attr_name, | ||
| hid_t | lapl_id | ||
| ) |
Removes an attribute from a specified location.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object, relative to location, from which attribute is to be removed |
| [in] | attr_name | Name of attribute to delete |
| [in] | lapl_id | Link access property list identifier |
H5Adelete_by_name() removes the attribute attr_name from an object specified by location and name, loc_id and obj_name, respectively.
If loc_id fully specifies the object from which the attribute is to be removed, obj_name should be '.' (a dot).
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
Determines whether an attribute with a given name exists on an object.
| [in] | obj_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | attr_name | Attribute name |
H5Aexists() determines whether the attribute attr_name exists on the object specified by obj_id.
| htri_t H5Aexists_by_name | ( | hid_t | obj_id, |
| const char * | obj_name, | ||
| const char * | attr_name, | ||
| hid_t | lapl_id | ||
| ) |
Determines whether an attribute with a given name exists on an object.
| [in] | obj_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Object name |
| [in] | attr_name | Attribute name |
| [in] | lapl_id | Link access property list identifier |
H5Aexists_by_name() determines whether the attribute attr_name exists on an object. That object is specified by its location and name, loc_id and obj_name, respectively.
loc_id specifies a location in the file containing the object. obj_name is the name of the object to which the attribute is attached and can be a relative name, relative to loc_id, or an absolute name, based in the root group of the file. If loc_id fully specifies the object, obj_name should be '.' (a dot).
The link access property list, lapl_id, may provide information regarding the properties of links required to access obj_name.
Gets an attribute creation property list identifier.
| [in] | attr_id | Attribute identifier |
H5Aget_create_plist() returns an identifier for the attribute creation property list associated with the attribute specified by attr_id.
The creation property list identifier should be released with H5Pclose().
| herr_t H5Aget_info | ( | hid_t | attr_id, |
| H5A_info_t * | ainfo | ||
| ) |
Retrieves attribute information, by attribute identifier.
| [in] | attr_id | Attribute identifier |
| [out] | ainfo | Attribute information struct |
H5Aget_info() retrieves attribute information, locating the attribute with an attribute identifier, attr_id, which is the identifier returned by H5Aopen() or H5Aopen_by_idx(). The attribute information is returned in the ainfo struct.
The ainfo struct is defined as follows:
corder_valid indicates whether the creation order data is valid for this attribute. Note that if creation order is not being tracked, no creation order data will be valid. Valid values are TRUE and FALSE.
corder is a positive integer containing the creation order of the attribute. This value is 0-based, so, for example, the third attribute created will have a corder value of 2.
cset indicates the character set used for the attribute’s name; valid values are defined in H5Tpublic.h and include the following:
| H5T_CSET_ASCII | US ASCII |
| H5T_CSET_UTF8 | UTF-8 Unicode encoding |
This value is set with H5Pset_char_encoding().
data_size indicates the size, in the number of characters, of the attribute.
| herr_t H5Aget_info_by_idx | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| H5A_info_t * | ainfo, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves attribute information by attribute index position.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object to which attribute is attached, relative to location |
| [in] | idx_type | Type of index |
| [in] | order | Index traversal order |
| [in] | n | Attribute’s position in index |
| [out] | ainfo | Struct containing returned attribute information |
| [in] | lapl_id | Link access property list identifier |
H5Aget_info_by_idx() retrieves information for an attribute that is attached to an object, which is specified by its location and name, loc_id and obj_name, respectively. The attribute is located by its index position and the attribute information is returned in the ainfo struct.
If loc_id fully specifies the object to which the attribute is attached, obj_name should be '.' (a dot).
The attribute is located by means of an index type, an index traversal order, and a position in the index, idx_type, order and n, respectively. These parameters and their valid values are discussed in the description of H5Aiterate2().
The ainfo struct, which will contain the returned attribute information, is described in H5Aget_info().
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
| herr_t H5Aget_info_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| const char * | attr_name, | ||
| H5A_info_t * | ainfo, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves attribute information, by attribute name.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object to which attribute is attached, relative to location |
| [in] | attr_name | Attribute name |
| [out] | ainfo | Struct containing returned attribute information |
| [in] | lapl_id | Link access property list identifier |
H5Aget_info_by_name() retrieves information for an attribute, attr_name, that is attached to an object specified by its location and name, loc_id and obj_name, respectively. The attribute information is returned in the ainfo struct.
If loc_id fully specifies the object to which the attribute is attached, obj_name should be '.' (a dot).
The ainfo struct is described in H5Aget_info().
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
Gets an attribute name.
| [in] | attr_id | Attribute identifier |
| [in] | buf_size | The size of the buffer to store the name in |
| [out] | buf | Buffer to store name in |
buf_size, if successful. Otherwise returns a negative value.H5Aget_name() retrieves the name of an attribute specified by the identifier, attr_id. Up to buf_size characters are stored in buf followed by a \0 string terminator. If the name of the attribute is longer than (buf_size -1), the string terminator is stored in the last position of the buffer to properly terminate the string.
If the user only wants to find out the size of this name, the values 0 and NULL can be passed in for the parameters bufsize and buf.
| ssize_t H5Aget_name_by_idx | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| char * | name, | ||
| size_t | size, | ||
| hid_t | lapl_id | ||
| ) |
Gets an attribute name, by attribute index position.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object to which attribute is attached, relative to location |
| [in] | idx_type | Type of index |
| [in] | order | Index traversal order |
| [in] | n | Attribute’s position in index |
| [out] | name | Attribute name |
| [in] | size | Size, in bytes, of attribute name |
| [in] | lapl_id | Link access property list identifier |
H5Aget_name_by_idx() retrieves the name of an attribute that is attached to an object, which is specified by its location and name, loc_id and obj_name, respectively. The attribute is located by its index position, the size of the name is specified in size, and the attribute name is returned in name.
If loc_id fully specifies the object to which the attribute is attached, obj_name should be '.' (a dot).
The attribute is located by means of an index type, an index traversal order, and a position in the index, idx_type, order and n, respectively. These parameters and their valid values are discussed in the description of H5Aiterate2().
If the attribute name’s size is unknown, the values 0 and NULL can be passed in for the parameters size and name. The function’s return value will provide the correct value for size.
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
| int H5Aget_num_attrs | ( | hid_t | loc_id | ) |
Determines the number of attributes attached to an object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
H5Aget_num_attrs() returns the number of attributes attached to the object specified by its identifier, loc_id.
Gets a copy of the dataspace for an attribute.
| [in] | attr_id | Attribute identifier |
H5Aget_space() retrieves a copy of the dataspace for an attribute. The dataspace identifier returned from this function must be released with H5Sclose() or resource leaks will develop.
| hsize_t H5Aget_storage_size | ( | hid_t | attr_id | ) |
Returns the amount of storage required for an attribute.
| [in] | attr_id | Attribute identifier |
H5Aget_storage_size() returns the amount of storage that is required for the specified attribute, attr_id.
Gets an attribute datatype.
| [in] | attr_id | Attribute identifier |
H5Aget_type() retrieves a copy of the datatype for an attribute. The datatype is reopened if it is a named type before returning it to the application. The datatypes returned by this function are always read-only. If an error occurs when atomizing the return datatype, then the datatype is closed.
The datatype identifier returned from this function must be released with H5Tclose() or resource leaks will develop.
| herr_t H5Aiterate1 | ( | hid_t | loc_id, |
| unsigned * | idx, | ||
| H5A_operator1_t | op, | ||
| void * | op_data | ||
| ) |
Calls a user’s function for each attribute on an object.
| [in] | loc_id | Location identifier |
| [in,out] | idx | Starting (in) and ending (out) attribute index |
| [in] | op | User's function to pass each attribute to |
| [in,out] | op_data | User's data to pass through to iterator operator function |
H5Aiterate1() iterates over the attributes of the object specified by its identifier, loc_id. The object can be a group, dataset, or named datatype. For each attribute of the object, the op_data and some additional information specified below are passed to the operator function op. The iteration begins with the attribute specified by its index, idx; the index for the next attribute to be processed by the operator, op, is returned in idx. If idx is the null pointer, then all attributes are processed.
op is a user-defined function whose prototype is defined as follows:
(Click on a enumerator, field, or type for more information.)
H5Aiterate was renamed to H5Aiterate1() and deprecated in this release. | herr_t H5Aiterate2 | ( | hid_t | loc_id, |
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t * | idx, | ||
| H5A_operator2_t | op, | ||
| void * | op_data | ||
| ) |
Calls user-defined function for each attribute on an object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | idx_type | Type of index |
| [in] | order | Order in which to iterate over index |
| [in,out] | idx | Initial and returned offset within index |
| [in] | op | User-defined function to pass each attribute to |
| [in,out] | op_data | User data to pass through to and to be returned by iterator operator function |
H5Aiterate2() iterates over the attributes attached to a dataset, named datatype, or group, as specified by loc_id. For each attribute, user-provided data, op_data, with additional information as defined below, is passed to a user-defined function, op, which operates on that attribute.
The order of the iteration and the attributes iterated over are specified by three parameters: the index type, idx_type; the order in which the index is to be traversed, order; and the attribute’s position in the index, idx.
The type of index specified by idx_type can be one of the following:
| H5_INDEX_NAME | Lexicographic order on name |
| H5_INDEX_CRT_ORDER | Index on creation order |
The order in which the index is to be traversed, as specified by order, can be one of the following:
| H5_ITER_INC | Increasing order |
| H5_ITER_DEC | Decreasing order |
| H5_ITER_NATIVE | Fastest available order |
The next attribute to be operated on is specified by idx, a position in the index.
For example, if idx_type, order, and idx are set to H5_INDEX_NAME, H5_ITER_INC, and 5, respectively, the attribute in question is the fifth attribute from the beginning of the alpha-numeric index of attribute names. If order were set to H5_ITER_DEC, it would be the fifth attribute from the end of the index.
The parameter idx is passed in on an H5Aiterate2() call with one value and may be returned with another value. The value passed in identifies the parameter to be operated on first; the value returned identifies the parameter to be operated on in the next step of the iteration.
op is a user-defined function whose prototype is defined as follows:
(Click on a enumerator, field, or type for more information.)
| herr_t H5Aiterate_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t * | idx, | ||
| H5A_operator2_t | op, | ||
| void * | op_data, | ||
| hid_t | lapl_id | ||
| ) |
Calls user-defined function for each attribute on an object.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object, relative to location |
| [in] | idx_type | Type of index |
| [in] | order | Order in which to iterate over index |
| [in,out] | idx | Initial and returned offset within index |
| [in] | op | User-defined function to pass each attribute to |
| [in,out] | op_data | User data to pass through to and to be returned by iterator operator function |
| [in] | lapl_id | Link access property list identifier |
H5Aiterate_by_name() iterates over the attributes attached to the dataset or group specified with loc_id and obj_name. For each attribute, user-provided data, op_data, with additional information as defined below, is passed to a user-defined function, op, which operates on that attribute.
If loc_id fully specifies the object to which these attributes are attached, obj_name should be '.' (a dot).
The order of the iteration and the attributes iterated over are specified by three parameters: the index type, idx_type; the order in which the index is to be traversed, order; and the attribute’s position in the index, idx.
The type of index specified by idx_type can be one of the following:
| H5_INDEX_NAME | Lexicographic order on name |
| H5_INDEX_CRT_ORDER | Index on creation order |
The order in which the index is to be traversed, as specified by order, can be one of the following:
| H5_ITER_INC | Increasing order |
| H5_ITER_DEC | Decreasing order |
| H5_ITER_NATIVE | Fastest available order |
The next attribute to be operated on is specified by idx, a position in the index.
For example, if idx_type, order, and idx are set to H5_INDEX_NAME, H5_ITER_INC, and 5, respectively, the attribute in question is the fifth attribute from the beginning of the alpha-numeric index of attribute names. If order were set to H5_ITER_DEC, it would be the fifth attribute from the end of the index.
The parameter idx is passed in on an H5Aiterate_by_name() call with one value and may be returned with another value. The value passed in identifies the parameter to be operated on first; the value returned identifies the parameter to be operated on in the next step of the iteration.
op is a user-defined function whose prototype is defined as follows:
(Click on a enumerator, field, or type for more information.)
Valid return values from an operator and the resulting H5Aiterate_by_name() and op behavior are as follows:
idx. idx.The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
Opens an attribute for an object specified by object identifier and attribute name.
| [in] | obj_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | attr_name | Name of attribute to open |
| [in] | aapl_id | Attribute access property list identifier |
H5Aopen() opens an existing attribute, attr_name, that is attached to object specified by an object identifier, obj_id.
The attribute access property list, aapl_id, is currently unused and should be H5P_DEFAULT.
This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called before the attribute can be accessed for any further purpose, including reading, writing, or any modification.
The attribute identifier returned by this function must be released with H5Aclose() or resource leaks will develop.
| hid_t H5Aopen_by_idx | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| hid_t | aapl_id, | ||
| hid_t | lapl_id | ||
| ) |
Opens the nth attribute attached to an object.
| [in] | loc_id | Location identifier |
| [in] | obj_name | Name of object to which attribute is attached, relative to location |
| [in] | idx_type | Type of index |
| [in] | order | Index traversal order |
| [in] | n | Attribute’s position in index |
| [in] | aapl_id | Attribute access property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Aopen_by_idx() opens an existing attribute that is attached to an object specified by location and name, loc_id and obj_name, respectively. If loc_id fully specifies the object to which the attribute is attached, obj_name, should be '.' (a dot).
The attribute is identified by an index type, an index traversal order, and a position in the index, idx_type, order and n, respectively. These parameters and their valid values are discussed in the description of H5Aiterate2().
The attribute access property list, aapl_id, is currently unused and should currently be H5P_DEFAULT.
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
This function, H5Aopen(), or H5Aopen_by_name() must be called before an attribute can be accessed for any further purpose, including reading, writing, or any modification.
The attribute identifier returned by this function must be released with H5Aclose() or resource leaks will develop.
| hid_t H5Aopen_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| const char * | attr_name, | ||
| hid_t | aapl_id, | ||
| hid_t | lapl_id | ||
| ) |
Opens an attribute for an object by object name and attribute name.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object to which attribute is attached, relative to loc_id |
| [in] | attr_name | Name of attribute to open |
| [in] | aapl_id | Attribute access property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Aopen_by_name() opens an existing attribute, attr_name, that is attached to an object specified by location and name, loc_id and obj_name, respectively.
loc_id specifies a location from which the target object can be located and obj_name is an object name relative to loc_id. If loc_id fully specifies the object to which the attribute is attached, obj_name should be '.' (a dot).
The attribute access property list, aapl_id, is currently unused and should currently be H5P_DEFAULT.
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
This function, H5Aopen(), or H5Aopen_by_idx() must be called before an attribute can be accessed for any further purpose, including reading, writing, or any modification.
The attribute identifier returned by this function must be released with H5Aclose() or resource leaks will develop.
Opens the attribute specified by its index.
| [in] | loc_id | Location identifier |
| [in] | idx | Index of the attribute to open |
H5Aopen_idx() opens an attribute which is attached to the object specified with loc_id . The location object may be either a group, dataset, or named datatype, all of which may have any sort of attribute. The attribute specified by the index, idx , indicates the attribute to access. The value of idx is a 0-based, non-negative integer. The attribute identifier returned from this function must be released with H5Aclose() or resource leaks will develop.
Opens an attribute specified by name.
| [in] | loc_id | Location identifier |
| [in] | name | Attribute name |
H5Aopen_name() opens an attribute specified by its name, name, which is attached to the object specified with loc_id. The location object may be either a group, dataset, or named datatype, which may have any sort of attribute. The attribute identifier returned from this function must be released with H5Aclose() or resource leaks will develop.
Reads the value of an attribute.
| [in] | attr_id | Attribute identifier |
| [in] | type_id | Datatype (in-memory) identifier |
| [out] | buf | Buffer for data to be read |
H5Aread() reads an attribute, specified with attr_id. The attribute's in-memory datatype is specified with type_id. The entire attribute is read into buf from the file.
Datatype conversion takes place at the time of a read or write and is automatic.
dims parameter was added to the Fortran API in this release. Renames an attribute.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | old_name | Name of the attribute to be changed |
| [in] | new_name | New name for the attribute |
H5Arename() changes the name of the attribute located at loc_id.
The old name, old_name, is changed to the new name, new_name.
| herr_t H5Arename_by_name | ( | hid_t | loc_id, |
| const char * | obj_name, | ||
| const char * | old_attr_name, | ||
| const char * | new_attr_name, | ||
| hid_t | lapl_id | ||
| ) |
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | obj_name | Name of object, relative to location, whose attribute is to be renamed |
| [in] | old_attr_name | Prior attribute name |
| [in] | new_attr_name | New attribute name |
| [in] | lapl_id | Link access property list identifier |
H5Arename_by_name() changes the name of attribute that is attached to the object specified by loc_id and obj_name. The attribute named old_attr_name is renamed new_attr_name.
The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.
Writes data to an attribute.
| [in] | attr_id | Attribute identifier |
| [in] | type_id | Datatype (in-memory) identifier |
| [out] | buf | Data to be written |
H5Awrite() writes an attribute, specified with attr_id. The attribute's in-memory datatype is specified with type_id. The entire attribute is written from buf to the file.
If type_id is either a fixed-length or variable-length string, it is important to set the string length when defining the datatype. String datatypes are derived from H5T_C_S1 (or H5T_FORTRAN_S1 for Fortran codes), which defaults to 1 character in size. See H5Tset_size() and Creating variable-length string datatypes.
Datatype conversion takes place at the time of a read or write and is automatic.
dims parameter added in this release 
1.8.17