Last modified: 4 December 2010
Name: H5Lget_val_by_idx
Signature:
  herr_t `H5Lget_val_by_idx`( hid_t `loc_id`, const char *`group_name`, H5_index_t `index_type`, H5_iter_order_t `order`, hsize_t `n`, void *`link_val`, size_t `size`, hid_t `lapl_id` )

Purpose:
  Retrieves value of the nth link in a group, according to the order within an index.

Description:
  `H5Lget_val_by_idx` retrieves the value of the nth link in a group, according to the specified order, `order`, within an index, `index`.
  - For soft links, the value is the path name of the object pointed to.
  - For external links, this is a compound value containing file and path name information; to use this external link information, it must first be decoded with `H5Lunpack_elink_val`
  - For user-defined links, this value will be described in the definition of the user-defined link type.
  - This function will fail if called on a hard link.

  `loc_id` specifies the file or group in which the group specified by `group_name` is located.

  `group_name` specifies the group in which the link exists. If `loc_id` already specifies the group in which the link exists, `group_name` must be a dot (.).

  The size in bytes of `group_name` is specified in `size`. If `size` is unknown, it can be determined via an initial `H5Lget_val_by_idx` call with `size` set to `NULL`; `size` will be returned with the actual size of `group_name`.

  If the type of the link is unknown or uncertain, `H5Lget_val_by_idx` should be called only after the type has been determined via a call to `H5Lget_info_by_idx`.

Parameters:

  hid_t `loc_id` | IN: File or group identifier specifying location of subject group
  const char *`group_name` | IN: Name of subject group
  H5_index_t `index_type` | IN: Type of index; valid values include: `NAME` Indexed by name `CORDER` Indexed by creation order
  H5_iter_order_t `order` | IN: Order within field or index; valid values include: `H5_ITER_INC` Iterate in increasing order `H5_ITER_DEC` Iterate in decreasing order `H5_ITER_NATIVE` Iterate in fastest order
  hsize_t `n` | IN: Link for which to retrieve information
  void *`link_val` | OUT: Pointer to buffer in which link value is returned
  size_t `size` | IN: Size in bytes of `group_name`
  hid_t `lapl_id` | IN: Link access property list

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

Fortran90 Interface:
  None.

History:

  Release | C
  1.8.0 | Function introduced in this release.