Detailed Description

Use the functions in this module to manage HDF5 attributes.

Like HDF5 datasets, HDF5 attributes are array variables which have an element datatype and a shape (dataspace). However, they perform a different function: Attributes decorate other HDF5 objects, and are typically used to represent application metadata. Unlike datasets, the HDF5 library does not support partial I/O operations for attributes and they cannot be compressed or extended.

Create	Read
14 { 15 __label__ fail_acpl, fail_attr, fail_file; 16 hid_t file, acpl, fspace, attr; 17 18 unsigned mode = H5F_ACC_TRUNC; 19 char file_name[] = "f1.h5"; 20 // attribute names can be arbitrary Unicode strings 21 char attr_name[] = "Χαρακτηριστικό"; 22 23 if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { 24 ret_val = EXIT_FAILURE; 25 goto fail_file; 26 } 27 if ((acpl = H5Pcreate(H5P_ATTRIBUTE_CREATE)) == H5I_INVALID_HID) { 28 ret_val = EXIT_FAILURE; 29 goto fail_acpl; 30 } 31 // use UTF-8 encoding for the attribute name 32 if (H5Pset_char_encoding(acpl, H5T_CSET_UTF8) < 0) { 33 ret_val = EXIT_FAILURE; 34 goto fail_fspace; 35 } 36 // create a scalar (singleton) attribute 37 if ((fspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) { 38 ret_val = EXIT_FAILURE; 39 goto fail_fspace; 40 } 41 // create an attribute on the root group 42 if ((attr = H5Acreate2(file, attr_name, H5T_STD_I32LE, fspace, acpl, H5P_DEFAULT)) == 43 H5I_INVALID_HID) { 44 ret_val = EXIT_FAILURE; 45 goto fail_attr; 46 } 47 48 H5Aclose(attr); 49fail_attr: 50 H5Sclose(fspace); 51fail_fspace: 52 H5Pclose(acpl); 53fail_acpl: 54 H5Fclose(file); 55fail_file:; 56 } H5F_ACC_TRUNC #define H5F_ACC_TRUNC Definition: H5Fpublic.h:90 H5I_INVALID_HID #define H5I_INVALID_HID Definition: H5Ipublic.h:66 hid_t int hid_t Definition: H5Ipublic.h:60 H5P_ATTRIBUTE_CREATE #define H5P_ATTRIBUTE_CREATE Definition: H5Ppublic.h:225 H5P_DEFAULT #define H5P_DEFAULT Definition: H5Ppublic.h:255 H5S_SCALAR @ H5S_SCALAR Definition: H5Spublic.h:72 H5T_CSET_UTF8 @ H5T_CSET_UTF8 Definition: H5Tpublic.h:201 H5Pset_char_encoding herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding) Sets the character encoding used to encode link and attribute names. H5Pclose herr_t H5Pclose(hid_t plist_id) Terminates access to a property list. H5Pcreate hid_t H5Pcreate(hid_t cls_id) Creates a new property list as an instance of a property list class. H5Acreate2 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. H5Aclose herr_t H5Aclose(hid_t attr_id) Closes the specified attribute. H5Fclose herr_t H5Fclose(hid_t file_id) Terminates access to an HDF5 file. H5Fcreate hid_t H5Fcreate(const char filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id) Creates an HDF5 file. H5Sclose herr_t H5Sclose(hid_t space_id) Releases and terminates access to a dataspace. H5Screate hid_t H5Screate(H5S_class_t type) Creates a new dataspace of a specified type. H5T_STD_I32LE #define H5T_STD_I32LE Definition: H5Tpublic.h:462	60 { 61 __label__ fail_attr, fail_file; 62 hid_t file, attr; 63 64 unsigned mode = H5F_ACC_RDONLY; 65 char file_name[] = "f1.h5"; 66 char attr_name[] = "Χαρακτηριστικό"; 67 int value; 68 69 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { 70 ret_val = EXIT_FAILURE; 71 goto fail_file; 72 } 73 if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) { 74 ret_val = EXIT_FAILURE; 75 goto fail_attr; 76 } 77 // read the attribute value 78 if (H5Aread(attr, H5T_NATIVE_INT, &value) < 0) 79 ret_val = EXIT_FAILURE; 80 81 // do something w/ the attribute value 82 83 H5Aclose(attr); 84fail_attr: 85 H5Fclose(file); 86fail_file:; 87 } H5F_ACC_RDONLY #define H5F_ACC_RDONLY Definition: H5Fpublic.h:88 H5Aopen 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. H5Aread herr_t H5Aread(hid_t attr_id, hid_t type_id, void buf) Reads the value of an attribute. H5Fopen hid_t H5Fopen(const char filename, unsigned flags, hid_t fapl_id) Opens an existing HDF5 file. H5T_NATIVE_INT #define H5T_NATIVE_INT Definition:* H5Tpublic.h:914
Update	Delete
91 { 92 __label__ fail_attr, fail_file; 93 hid_t file, attr; 94 95 unsigned mode = H5F_ACC_RDWR; 96 char file_name[] = "f1.h5"; 97 char attr_name[] = "Χαρακτηριστικό"; 98 int value = 1234; 99 100 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { 101 ret_val = EXIT_FAILURE; 102 goto fail_file; 103 } 104 if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) { 105 ret_val = EXIT_FAILURE; 106 goto fail_attr; 107 } 108 // update the attribute value 109 if (H5Awrite(attr, H5T_NATIVE_INT, &value) < 0) 110 ret_val = EXIT_FAILURE; 111 112 H5Aclose(attr); 113fail_attr: 114 H5Fclose(file); 115fail_file:; 116 } H5F_ACC_RDWR #define H5F_ACC_RDWR Definition: H5Fpublic.h:89 H5Awrite herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf) Writes data to an attribute.	120 { 121 __label__ fail_attr, fail_file; 122 hid_t file; 123 124 unsigned mode = H5F_ACC_RDWR; 125 char file_name[] = "f1.h5"; 126 char attr_name[] = "Χαρακτηριστικό"; 127 128 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { 129 ret_val = EXIT_FAILURE; 130 goto fail_file; 131 } 132 // delete the attribute 133 if (H5Adelete(file, attr_name) < 0) { 134 ret_val = EXIT_FAILURE; 135 goto fail_attr; 136 } 137 138fail_attr: 139 H5Fclose(file); 140fail_file:; 141 } H5Adelete herr_t H5Adelete(hid_t loc_id, const char *attr_name) Deletes an attribute from a specified location.

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 used to store an attribute. More...

hid_t	H5Aget_type (hid_t attr_id)
	Gets an attribute's 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 a 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...

Macro Definition Documentation

◆ H5Acreate

#define H5Acreate H5Acreate2

H5Acreate() is a macro that is mapped to either H5Acreate1() or H5Acreate2().

See also: API Compatibility Macros

◆ H5Aiterate

#define H5Aiterate H5Aiterate2

H5Aiterate() is a macro that is mapped to either H5Aiterate1() or H5Aiterate2().

See also: API Compatibility Macros

Function Documentation

◆ H5Aclose()

herr_t H5Aclose ( hid_t attr_id )

Closes the specified attribute.

Parameters

[in] attr_id Attribute identifier

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

H5Aclose() terminates access to the attribute through attr_id and releases the identifier.

Example: {

__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[] = "Χαρακτηριστικό";

if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_file;

}

if ((acpl = H5Pcreate(H5P_ATTRIBUTE_CREATE)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_acpl;

}

// use UTF-8 encoding for the attribute name

if (H5Pset_char_encoding(acpl, H5T_CSET_UTF8) < 0) {

ret_val = EXIT_FAILURE;

goto fail_fspace;

}

// create a scalar (singleton) attribute

if ((fspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_fspace;

}

// create an attribute on the root group

if ((attr = H5Acreate2(file, attr_name, H5T_STD_I32LE, fspace, acpl, H5P_DEFAULT)) ==

H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_attr;

}

H5Aclose(attr);

fail_attr:

H5Sclose(fspace);

fail_fspace:

H5Pclose(acpl);

fail_acpl:

H5Fclose(file);

fail_file:;

}

Since: 1.0.0

See also: H5Acreate(), H5Aopen()

◆ H5Acreate1()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

Deprecated:: Superseded by H5Acreate2().

Note: The acpl parameter 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.

Since: 1.8.0

Version: 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and deprecated in this release.

See also: H5Aclose()

◆ H5Acreate2()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

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.

Note: The acpl parameter is currently not used; specify H5P_DEFAULT.

The attribute identifier returned by this function must be released with H5Aclose() resource leaks will develop.

Note: If loc_id is a file identifier, the attribute will be attached that file’s root group.

Example: {

__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[] = "Χαρακτηριστικό";

if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_file;

}

if ((acpl = H5Pcreate(H5P_ATTRIBUTE_CREATE)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_acpl;

}

// use UTF-8 encoding for the attribute name

if (H5Pset_char_encoding(acpl, H5T_CSET_UTF8) < 0) {

ret_val = EXIT_FAILURE;

goto fail_fspace;

}

// create a scalar (singleton) attribute

if ((fspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_fspace;

}

// create an attribute on the root group

if ((attr = H5Acreate2(file, attr_name, H5T_STD_I32LE, fspace, acpl, H5P_DEFAULT)) ==

H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_attr;

}

H5Aclose(attr);

fail_attr:

H5Sclose(fspace);

fail_fspace:

H5Pclose(acpl);

fail_acpl:

H5Fclose(file);

fail_file:;

}

Since: 1.8.0

See also: H5Aclose()

◆ H5Acreate_by_name()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

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.

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.

Note: The aapl parameter is currently not used; specify H5P_DEFAULT.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Adelete()

herr_t H5Adelete	(	hid_t	loc_id,
		const char *	attr_name
	)

Deletes an attribute from a specified location.

Parameters

[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

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

H5Adelete() removes the attribute specified by its name, attr_name, from a file, dataset, group, or named datatype.

Attention: This function should not be used when other attribute identifiers are open on loc_id. This may cause the internal indexes of the attributes to change and future writes to the open attributes to produce incorrect results.

Example: {

__label__ fail_attr, fail_file;

hid_t file;

unsigned mode = H5F_ACC_RDWR;

char file_name[] = "f1.h5";

char attr_name[] = "Χαρακτηριστικό";

if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {

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:;

}

Since: 1.0.0

◆ H5Adelete_by_idx()

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.

Parameters

[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

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

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.

The attribute to be removed is specified by a position in an index, n. The type of index is specified by idx_type. The order in which the index is to be traversed is specified by order. For example, if idx_type, order, and n are set to H5_INDEX_NAME, H5_ITER_INC, and 5, respectively, the fifth attribute in lexicographic order of attribute names will be removed.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Adelete_by_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.

Parameters

[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

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

H5Adelete_by_name() removes the attribute attr_name from an object specified by location and name, loc_id and obj_name, respectively.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Aexists()

htri_t H5Aexists	(	hid_t	obj_id,
		const char *	attr_name
	)

Determines whether an attribute with a given name exists on an object.

Parameters

[in]	obj_id	Location identifier. The identifier may be that of a file, group, dataset, or named datatype.
[in]	attr_name	Attribute name

Returns: Returns zero (false), a positive (true) or a negative (failure) value.

H5Aexists() determines whether the attribute attr_name exists on the object specified by obj_id.

Since: 1.8.0

◆ H5Aexists_by_name()

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.

Parameters

[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

Returns: Returns zero (false), a positive (true) or a negative (failure) value.

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.

The link access property list, lapl_id, may provide information regarding the properties of links required to access obj_name.

Since: 1.8.0

◆ H5Aget_create_plist()

hid_t H5Aget_create_plist ( hid_t attr_id )

Gets an attribute creation property list identifier.

Parameters

[in] attr_id Attribute identifier

Returns: Returns an attribute's creation property list identifier if successful; otherwise returns a negative value.

H5Aget_create_plist() returns an identifier for the attribute creation property list associated with the attribute specified by attr_id.

Since: 1.8.0

◆ H5Aget_info()

herr_t H5Aget_info	(	hid_t	attr_id,
		H5A_info_t *	ainfo
	)

Retrieves attribute information, by attribute identifier.

Parameters

[in]	attr_id	Attribute identifier
[out]	ainfo	Attribute information struct

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

H5Aget_info() retrieves attribute information, locating the attribute with an attribute identifier, attr_id. The attribute information is returned in the ainfo struct.

Since: 1.8.0

◆ H5Aget_info_by_idx()

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.

Parameters

[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

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

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.

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.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Aget_info_by_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.

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file, group, dataset, or named datatype.
[in]	obj_name	Name of the object to which an 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

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

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.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Aget_name()

ssize_t H5Aget_name	(	hid_t	attr_id,
		size_t	buf_size,
		char *	buf
	)

Gets an attribute name.

Parameters

[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

Returns: Returns the length of the attribute's name, which may be longer than 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 retrieve the name length, the values 0 and NULL should be passed for the parameters bufsize and buf.

Since: 1.0.0

◆ H5Aget_name_by_idx()

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.

Parameters

[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

Returns: Returns attribute name size, in bytes, if successful; otherwise returns a negative value.

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.

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.

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.

Since: 1.8.0

◆ H5Aget_num_attrs()

int H5Aget_num_attrs ( hid_t loc_id )

Determines the number of attributes attached to an object.

Parameters

[in] loc_id Location identifier. The identifier may be that of a file, group, dataset, or named datatype.

Returns: Returns the number of attributes if successful; otherwise returns a negative value.

Deprecated:: Superseded by H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx().

H5Aget_num_attrs() returns the number of attributes attached to the object specified by its identifier, loc_id.

Since: 1.0.0

◆ H5Aget_space()

hid_t H5Aget_space ( hid_t attr_id )

Gets a copy of the dataspace for an attribute.

Parameters

[in] attr_id Attribute identifier

Returns: Returns an attribute dataspace identifier if successful; otherwise returns a negative value.

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.

Since: 1.0.0

◆ H5Aget_storage_size()

hsize_t H5Aget_storage_size ( hid_t attr_id )

Returns the amount of storage used to store an attribute.

Parameters

[in] attr_id Attribute identifier

Returns: Returns the amount of storage size allocated for the attribute; otherwise returns 0 (zero).

H5Aget_storage_size() returns the amount of storage that is required for the specified attribute, attr_id.

Since: 1.6.0

◆ H5Aget_type()

hid_t H5Aget_type ( hid_t attr_id )

Gets an attribute's datatype.

Parameters

[in] attr_id Attribute identifier

Returns: Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

H5Aget_type() retrieves a copy of the attribute's datatype. 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.

The datatype identifier returned from this function must be released with H5Tclose() or resource leaks will develop.

Since: 1.0.0

◆ H5Aiterate1()

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.

Parameters

[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

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

Deprecated:: Superseded by H5Aiterate2().

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.

Version: 1.8.0 The function H5Aiterate was renamed to H5Aiterate1() and deprecated in this release.

Since: 1.0.0

◆ H5Aiterate2()

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 a user-defined function for each attribute on an object.

Parameters

[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

Returns: Returns a non-negative value if successful; otherwise returns a negative value. Further note that this function returns the return value of the last operator if it was non-zero, which can be a negative value, zero if all attributes were processed, or a positive value indicating short-circuit success.

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 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 alphanumeric 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.

Note: This function is also available through the H5Aiterate() macro.

Since: 1.8.0

◆ H5Aiterate_by_name()

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.

Parameters

[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

Returns: Returns a non-negative value if successful; otherwise returns a negative value. Further note that this function returns the return value of the last operator if it was non-zero, which can be a negative value, zero if all attributes were processed, or a positive value indicating short-circuit success.

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.

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 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 alphanumeric 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.

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name.

Since: 1.8.0

◆ H5Aopen()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

H5Aopen() opens an existing attribute, attr_name, that is attached to object specified by an object identifier, obj_id.

Note: The aapl_id parameter is currently not used; specify 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.

Example: {

__label__ fail_attr, fail_file;

hid_t file, attr;

unsigned mode = H5F_ACC_RDONLY;

char file_name[] = "f1.h5";

char attr_name[] = "Χαρακτηριστικό";

int value;

if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_file;

}

if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_attr;

}

// read the attribute value

if (H5Aread(attr, H5T_NATIVE_INT, &value) < 0)

ret_val = EXIT_FAILURE;

// do something w/ the attribute value

H5Aclose(attr);

fail_attr:

H5Fclose(file);

fail_file:;

}

Since: 1.8.0

See also: H5Aclose(), H5Acreate()

◆ H5Aopen_by_idx()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

H5Aopen_by_idx() opens an existing attribute that is attached to an object specified by location and name, loc_id and obj_name, respectively.

The attribute is identified by an index type, an index traversal order, and a position in the index, idx_type, order and n, respectively.

Note: The aapl_id parameter is currently not used; specify 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.

Since: 1.8.0

◆ H5Aopen_by_name()

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.

Parameters

[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

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

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.

Note: The aapl_id parameter is currently not used; specify 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.

Since: 1.8.0

◆ H5Aopen_idx()

hid_t H5Aopen_idx	(	hid_t	loc_id,
		unsigned	idx
	)

Opens the attribute specified by its index.

Parameters

[in]	loc_id	Location identifier
[in]	idx	Index of the attribute to open

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

Deprecated:: Superseded by H5Aopen_by_idx().

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.

Since: 1.0.0

◆ H5Aopen_name()

hid_t H5Aopen_name	(	hid_t	loc_id,
		const char *	name
	)

Opens an attribute specified by name.

Parameters

[in]	loc_id	Location identifier
[in]	name	Attribute name

Returns: Returns an attribute identifier if successful; otherwise returns a negative value.

Deprecated:: Superseded by H5Aopen_by_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.

Since: 1.0.0

◆ H5Aread()

herr_t H5Aread	(	hid_t	attr_id,
		hid_t	type_id,
		void *	buf
	)

Reads the value of an attribute.

Parameters

[in]	attr_id	Attribute identifier
[in]	type_id	Datatype (in-memory) identifier
[out]	buf	Buffer for data to be read

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

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.

Example: {

__label__ fail_attr, fail_file;

hid_t file, attr;

unsigned mode = H5F_ACC_RDONLY;

char file_name[] = "f1.h5";

char attr_name[] = "Χαρακτηριστικό";

int value;

if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_file;

}

if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_attr;

}

// read the attribute value

if (H5Aread(attr, H5T_NATIVE_INT, &value) < 0)

ret_val = EXIT_FAILURE;

// do something w/ the attribute value

H5Aclose(attr);

fail_attr:

H5Fclose(file);

fail_file:;

}

Version: 1.8.8 Fortran updated to Fortran2003.; 1.4.2 The dims parameter was added to the Fortran API in this release.

Since: 1.0.0

See also: H5Awrite()

◆ H5Arename()

herr_t H5Arename	(	hid_t	loc_id,
		const char *	old_name,
		const char *	new_name
	)

Renames an attribute.

Parameters

[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

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

H5Arename() changes the name of the attribute located at loc_id.

The old name, old_name, is changed to the new name, new_name.

Since: 1.6.0

◆ H5Arename_by_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
	)

Parameters

[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.

Since: 1.8.0

◆ H5Awrite()

herr_t H5Awrite	(	hid_t	attr_id,
		hid_t	type_id,
		const void *	buf
	)

Writes data to an attribute.

Parameters

[in]	attr_id	Attribute identifier
[in]	type_id	Datatype (in-memory) identifier
[out]	buf	Data to be written

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

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.

Datatype conversion takes place at the time of a read or write and is automatic.

Example: {

__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;

if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_file;

}

if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) {

ret_val = EXIT_FAILURE;

goto fail_attr;

}

// update the attribute value

if (H5Awrite(attr, H5T_NATIVE_INT, &value) < 0)

ret_val = EXIT_FAILURE;

H5Aclose(attr);

fail_attr:

H5Fclose(file);

fail_file:;

}

Version: 1.8.8 Fortran updated to Fortran2003.; 1.4.2 Fortran dims parameter added in this release

Since: 1.0.0

See also: H5Aread()

Detailed Description

Macros

Functions

Macro Definition Documentation

◆ H5Acreate

◆ H5Aiterate

Function Documentation

◆ H5Aclose()

◆ H5Acreate1()

◆ H5Acreate2()

◆ H5Acreate_by_name()

◆ H5Adelete()

◆ H5Adelete_by_idx()

◆ H5Adelete_by_name()

◆ H5Aexists()

◆ H5Aexists_by_name()

◆ H5Aget_create_plist()

◆ H5Aget_info()

◆ H5Aget_info_by_idx()

◆ H5Aget_info_by_name()

◆ H5Aget_name()

◆ H5Aget_name_by_idx()

◆ H5Aget_num_attrs()

◆ H5Aget_space()

◆ H5Aget_storage_size()

◆ H5Aget_type()

◆ H5Aiterate1()

◆ H5Aiterate2()

◆ H5Aiterate_by_name()

◆ H5Aopen()

◆ H5Aopen_by_idx()

◆ H5Aopen_by_name()

◆ H5Aopen_idx()

◆ H5Aopen_name()

◆ H5Aread()

◆ H5Arename()

◆ H5Arename_by_name()

◆ H5Awrite()