Last modified: 9 October 2014
Name: H5Acreate_by_name
Signature:
  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` )

Purpose:
  Creates an attribute attached to a specified object.

Description:
  `H5Acreate_by_name` creates an attribute, `attr_name`, which is attached to the object specified by `loc_id` and `obj_name`.

  `loc_id` is a location identifier; `obj_name` is the object name relative to `loc_id`. If `loc_id` fully specifies the object to which the attribute is to be attached, `obj_name` should be `'.'` (a dot).

  The attribute name, `attr_name`, must be unique for the object.

  The attribute is created with the specified datatype and dataspace, `type_id` and `space_id`, which are created with the H5T and H5S interfaces respectively.

  The attribute creation and access property lists are currently unused, but will be used in the future for optional attribute creation and access properties. These property lists should currently be `H5P_DEFAULT`.

  The link access property list, `lapl_id`, may provide information regarding the properties of links required to access the object, `obj_name`. See “Link Access Properties” in the H5P APIs.

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

Parameters:

  hid_t `loc_id` | IN: Location or object identifier; may be dataset or group
  const char *`obj_name` | IN: Name, relative to `loc_id`, of object that attribute is to be attached to
  const char *`attr_name` | IN: Attribute name
  hid_t `type_id` | IN: Attribute datatype identifier
  hid_t `space_id` | IN: Attribute dataspace identifier
  hid_t `acpl_id` | IN: Attribute creation property list identifier (Currently not used.)
  hid_t `aapl_id` | IN: Attribute access property list identifier (Currently not used.)
  hid_t `lapl_id` | IN: Link access property list

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

Fortran90 Interface: h5acreate_by_name_f

      SUBROUTINE h5acreate_by_name_f(loc_id, obj_name, attr_name, type_id, space_id, &
           attr, hdferr, acpl_id, aapl_id, lapl_id)

        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: loc_id      ! Object identifier
        CHARACTER(LEN=*), INTENT(IN) :: obj_name  ! Name of object to which
                                                  ! attribute is attached
        CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name
        INTEGER(HID_T), INTENT(IN) :: type_id     ! Attribute datatype identifier
        INTEGER(HID_T), INTENT(IN) :: space_id    ! Attribute dataspace identifier
        INTEGER(HID_T), INTENT(OUT) :: attr       ! An attribute identifier
        INTEGER, INTENT(OUT) :: hdferr            ! Error code:
                                                  ! 0 on success and -1 on failure
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: acpl_id
                                                  ! Attribute creation property list
                                                  ! identifier (Currently not used.)
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id
                                                  ! Attribute access property list
                                                  ! identifier (Currently not used.)
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
                                                  ! Link access property list
      END SUBROUTINE h5acreate_by_name_f

See Also:
  “Using Identifiers”

History:

  Release | C
  1.8.0 | Function introduced in this release.