Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Attributes (H5A)

## Detailed Description

An HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. A primary data object may be a dataset, group, or committed datatype.

See also
  HDF5 Attributes

## Macros
#define | H5Acreate H5Acreate2
#define | H5Aiterate H5Aiterate2

## Functions
herr_t | H5Aclose (hid_t attr_id)
| Closes the specified attribute.
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.
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.
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.
herr_t | H5Adelete (hid_t loc_id, const char *attr_name)
| Deletes an attribute from a specified location.
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.
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.
htri_t | H5Aexists (hid_t obj_id, const char *attr_name)
| Determines whether an attribute with a given name exists on an object.
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.
hid_t | H5Aget_create_plist (hid_t attr_id)
| Gets an attribute creation property list identifier.
herr_t | H5Aget_info (hid_t attr_id, H5A_info_t *ainfo)
| Retrieves attribute information by attribute identifier.
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.
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.
ssize_t | H5Aget_name (hid_t attr_id, size_t buf_size, char *buf)
| Gets an attribute name.
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.
int | H5Aget_num_attrs (hid_t loc_id)
| Determines the number of attributes attached to an object.
hid_t | H5Aget_space (hid_t attr_id)
| Gets a copy of the dataspace for an attribute.
hsize_t | H5Aget_storage_size (hid_t attr_id)
| Returns the amount of storage used to store an attribute.
hid_t | H5Aget_type (hid_t attr_id)
| Gets an attribute's datatype.
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.
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.
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.
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.
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.
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.
hid_t | H5Aopen_idx (hid_t loc_id, unsigned idx)
| Opens the attribute specified by its index.
hid_t | H5Aopen_name (hid_t loc_id, const char *name)
| Opens an attribute specified by name.
herr_t | H5Aread (hid_t attr_id, hid_t type_id, void *buf)
| Reads the value of an attribute.
herr_t | H5Arename (hid_t loc_id, const char *old_name, const char *new_name)
| Renames an attribute.
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)
herr_t | H5Awrite (hid_t attr_id, hid_t type_id, const void *buf)
| Writes data to an attribute.

## 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 H5I_INVALID_HID.

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

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 `aapl_id` parameter is currently not used; specify H5P_DEFAULT.

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

Note
  If `loc_id` is a file identifier, the attribute will be attached to 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 H5I_INVALID_HID.

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_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`.

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 the index
  [in] | n | Offset within the 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 the 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 on 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 H5I_INVALID_HID.

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() to prevent resource leaks.

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 `size` characters of the attribute name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the attribute name, which determines the required value of `size`, is unknown, a preliminary call to H5Aget_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the attribute name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Aget_name() call, which will retrieve the actual attribute name.

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.

Up to `size` characters of the attribute name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the attribute name, which determines the required value of `size`, is unknown, a preliminary call to H5Aget_name_by_idx() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the attribute name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Aget_name_by_idx() call, which will retrieve the actual attribute 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

## ◆ 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 H5I_INVALID_HID.

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

Warning
  Adding or removing attributes to the object during iteration will lead to undefined behavior.

Attention
  Leaving callback functions:
  The callback function must return normally, even in the case of error. Returning with H5_ITER_ERROR, instead of leaving by means of exceptions, exit() function, etc... will allow the HDF5 library to manage its resources and maintain a consistent state. See C++ Developers using HDF5 C-API functions warning for detail.

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.

Warning
  Adding or removing attributes to the object during iteration will lead to undefined behavior.

Attention
  Leaving callback functions:
  The callback function must return normally, even in the case of error. Returning with H5_ITER_ERROR, instead of leaving by means of exceptions, exit() function, etc... will allow the HDF5 library to manage its resources and maintain a consistent state. See C++ Developers using HDF5 C-API functions warning for detail.

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 is 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`.

Warning
  Adding or removing attributes to the object during iteration will lead to undefined behavior.

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

H5Aopen() opens an existing attribute, `attr_name`, that is attached to the 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 H5I_INVALID_HID.

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

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

Deprecated
  Superseded by H5Aopen_by_idx().

H5Aopen_idx() opens an attribute that 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 H5I_INVALID_HID.

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
  [in] | 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()