Last modified: 24 September 2014
Name: H5Lget_info
Signature:
  herr_t `H5Lget_info`( hid_t `link_loc_id`, const char *`link_name`, H5L_info_t *`link_buff`, hid_t `lapl_id` )

Purpose:
  Returns information about a link.

Description:
  `H5Lget_info` returns information about the specified link through the `link_buff` argument.

  A file or group identifier, `link_loc_id`, specifies the location of the link. A link name, `link_name`, interpreted relative to `loc_id`, specifies the link being queried.

  `lapl_id` is the link access property list associated with the link `link_name`. In the general case, when default link access properties are acceptable, this can be passed in as `H5P_DEFAULT`. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see `H5Pset_elink_prefix`).

  `H5Lget_info` returns information about `link_name` in the data structure `H5L_info_t`, which is described below and defined in `H5Lpublic.h`. This structure is returned in the buffer `link_buff`.

          typedef struct {
              H5L_type_t     type;
              hbool_t        corder_valid;
              int64_t        corder;
              H5T_cset_t     cset;
              union {
                  haddr_t    address;
                  size_t     val_size;
              } u;
          } H5L_info_t;

  In the above struct, `type` specifies the link class. Valid values include the following:

  | `H5L_TYPE_HARD` | Hard link
  | `H5L_TYPE_SOFT` | Soft link
  | `H5L_TYPE_EXTERNAL` | External link
  | `H5L_TYPE_ERROR` | Error

  There will be additional valid values if user-defined links have been registered.

  `corder` specifies the link’s creation order position while `corder_valid` indicates whether the value in `corder` is valid.

  If `corder_valid` is `TRUE`, the value in `corder` is known to be valid; if `corder_valid` is `FALSE`, the value in `corder` is presumed to be invalid;

  `corder` starts at zero (`0`) and is incremented by one (`1`) as new links are created. But higher-numbered entries are not adjusted when a lower-numbered link is deleted; the deleted link’s creation order position is simply left vacant. In such situations, the value of `corder` for the last link created will be larger than the number of links remaining in the group.

  `cset` specifies the character set in which the link name is encoded. Valid values include the following:

  | `H5T_CSET_ASCII` | US ASCII
  | `H5T_CSET_UTF8` | UTF-8 Unicode encoding

  This value is set with `H5Pset_char_encoding`.

  `address` and `val_size` are returned for hard and symbolic links, respectively. Symbolic links include soft and external links and some user-defined links.

  If the link is a hard link, `address` specifies the file address that the link points to.

  If the link is a symbolic link, `val_size` will be the length of the link value, e.g., the length of the name of the pointed-to object with a null terminator.

Parameters:

  hid_t `link_loc_id` | IN: File or group identifier.
  const char `*link_name` | IN: Name of the link for which information is being sought.
  H5L_info_t `*link_buff` | OUT: Buffer in which link information is returned.
  hid_t `lapl_id` | IN: Link access property list identifier.

Returns:
  Returns a non-negative value if successful, with the fields of `link_buff` (if non-null) initialized. Otherwise returns a negative value.

Fortran90 Interface: h5lget_info_f

      SUBROUTINE h5lget_info_f(link_loc_id, link_name, &
           cset, corder, f_corder_valid, link_type, address, val_size, &
           hdferr, lapl_id)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: link_loc_id
                              ! File or group identifier.
        CHARACTER(LEN=*), INTENT(IN) :: link_name
                              ! Name of the link for which information is being sought.
        INTEGER, INTENT(OUT) :: cset
                              ! Indicates the character set used for the link’s name.
        INTEGER, INTENT(OUT) :: corder
                              ! Specifies the link’s creation order position.
        LOGICAL, INTENT(OUT) :: f_corder_valid
                              ! Indicates whether the value in corder is valid.
        INTEGER, INTENT(OUT) :: link_type
                              ! Specifies the link class:
                              !  H5L_TYPE_HARD_F      - Hard link
                              !  H5L_TYPE_SOFT_F      - Soft link
                              !  H5L_TYPE_EXTERNAL_F  - External link
                              !  H5L_TYPE_ERROR_F     - Error
        INTEGER(HADDR_T), INTENT(OUT) :: address
                              ! If the link is a hard link, address specifies the file
                              ! address that the link points to
        INTEGER(SIZE_T), INTENT(OUT) :: val_size
                              ! If the link is a symbolic link, val_size will be the
                              ! length of the link value, i.e. the length of the name
                              ! of the pointed-to object with a null terminator.

        INTEGER, INTENT(OUT) :: hdferr
                              ! Error code:
                              ! 0 on success and -1 on failure
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
                              ! Link access property list
      END SUBROUTINE h5lget_info_f

History:

  Release | C
  1.8.0 | Function introduced in this release.
  1.8.2 | Fortran subroutine added in this release.
  1.8.4 | Fortran subroutine syntax changed in this release.