Last modified: 3 April 2013
Name: H5Aget_name_by_idx
Signature:
  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` )

Purpose:
  Gets an attribute name, by attribute index position

Description:
  `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`. See “Link Access Properties” in the H5P APIs.

Note:

Parameters:

  hid_t `loc_id` | IN: Location of object to which attribute is attached
  const char *`obj_name` | IN: Name of object to which attribute is attached, relative to location
  H5_index_t `idx_type` | IN: Type of index
  H5_iter_order_t `order` | IN: Index traversal order
  hsize_t `n` | IN: Attribute’s position in index
  char *`name` | OUT: Attribute name
  size_t `size` | IN: Size, in bytes, of attribute name
  hid_t `lapl_id` | IN: Link access property list

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

Fortran90 Interface: h5aget_name_by_idx_f

      SUBROUTINE h5aget_name_by_idx_f(loc_id, obj_name, idx_type, order, &
             n, name, size, lapl_id, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifer for object to which
                                             ! attribute is attached
        CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object, relative to
                                                 ! location,from which attribute is to
                                                 ! be removed
        INTEGER, INTENT(IN) :: idx_type
                                     ! Type of index; Possible values are:
                                     !  H5_INDEX_UNKNOWN_F   - Unknown index type
                                     !  H5_INDEX_NAME_F      - Index on names
                                     !  H5_INDEX_CRT_ORDER_F - Index on creation order
                                     !  H5_INDEX_N_F         - Number indices defined

        INTEGER, INTENT(IN) :: order ! Order in which to iterate over index:
                                     !  H5_ITER_UNKNOWN_F - Unknown order
                                     !  H5_ITER_INC_F     - Increasing order
                                     !  H5_ITER_DEC_F     - Decreasing order
                                     !  H5_ITER_NATIVE_F  - No particular order,
                                     !                      whatever is fastest
                                     !  H5_ITER_N_F       - Number of iteration orders

        INTEGER(HSIZE_T), INTENT(IN) :: n
                                     ! Attribute’s position in index
        CHARACTER(LEN=*), INTENT(OUT) :: name
                                     ! Attribute name
        INTEGER(SIZE_T), INTENT(INOUT) :: size
                                     ! Buffer size
        INTEGER(HID_T), INTENT(IN) :: lapl_id
                                     ! Link access property list
        INTEGER, INTENT(OUT) :: hdferr
                                     ! Error code:
                                     !  Returns attribute name size,
                                     !  -1 if fail
      END SUBROUTINE h5aget_name_by_idx_f

History:

  Release | C
  1.8.0 | Function introduced in this release.