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
Links (H5L)

## Detailed Description

Use the functions in this module to manage HDF5 links and link types.

See also
  Link Traversal for H5Literate, H5Literate_by_name and H5Lvisit, H5Lvisit_by_name
  Advanced Link Functions for H5Lregister, H5Lunregister and H5Lis_registered

## Topics
| Advanced Link Functions
| Link Traversal

## Macros
#define | H5Lget_info H5Lget_info2
#define | H5Lget_info_by_idx H5Lget_info_by_idx2

## Functions
herr_t | H5Lcopy (hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
| Creates an identical copy of a link with the same creation time and target. The new link can have a different name and be in a different location than the original.
herr_t | H5Lcreate_external (const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id)
| Creates an external link, a soft link to an object in a different file.
herr_t | H5Lcreate_hard (hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
| Creates a hard link to an object.
herr_t | H5Lcreate_soft (const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id)
| Creates a soft link.
herr_t | H5Lcreate_ud (hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id)
| Creates a link of a user-defined type.
herr_t | H5Ldelete (hid_t loc_id, const char *name, hid_t lapl_id)
| Removes a link from a group.
herr_t | H5Ldelete_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id)
| Removes the n-th link in a group.
htri_t | H5Lexists (hid_t loc_id, const char *name, hid_t lapl_id)
| Determines whether a link with the specified name exists in a group.
herr_t | H5Lget_info1 (hid_t loc_id, const char *name, H5L_info1_t *linfo, hid_t lapl_id)
| Returns information about a link.
herr_t | H5Lget_info2 (hid_t loc_id, const char *name, H5L_info2_t *linfo, hid_t lapl_id)
| Returns information about a link.
herr_t | H5Lget_info_by_idx1 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info1_t *linfo, hid_t lapl_id)
| Retrieves metadata for a link in a group, according to the order within a field or index.
herr_t | H5Lget_info_by_idx2 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id)
| Retrieves metadata for a link in a group, according to the order within a field or index.
ssize_t | H5Lget_name_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id)
| Retrieves name of the n-th link in a group, according to the order within a specified field or index.
herr_t | H5Lget_val (hid_t loc_id, const char *name, void *buf, size_t size, hid_t lapl_id)
| Returns the value of a link.
herr_t | H5Lget_val_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, void *buf, size_t size, hid_t lapl_id)
| Retrieves value of the n-th link in a group, according to the order within an index.
herr_t | H5Lmove (hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
| Moves a link within an HDF5 file.
herr_t | H5Lunpack_elink_val (const void *ext_linkval, size_t link_size, unsigned *flags, const char **filename, const char **obj_path)
| Decodes external link information.

## Macro Definition Documentation

## ◆ H5Lget_info

#define H5Lget_info H5Lget_info2

H5Lget_info() is a macro that is mapped to either H5Lget_info1() or H5Lget_info2().

See also
  API Compatibility Macros

## ◆ H5Lget_info_by_idx

#define H5Lget_info_by_idx H5Lget_info_by_idx2

H5Lget_info_by_idx() is a macro that is mapped to either H5Lget_info_by_idx1() or H5Lget_info_by_idx2().

See also
  API Compatibility Macros

## Function Documentation

## ◆ H5Lcopy()

herr_t H5Lcopy | ( | hid_t | src_loc,
|  | const char * | src_name,
|  | hid_t | dst_loc,
|  | const char * | dst_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates an identical copy of a link with the same creation time and target. The new link can have a different name and be in a different location than the original.

Parameters

  [in] | src_loc | Location identifier. The identifier may be that of a file, group, dataset, or named datatype.
  [in] | src_name | Name of the link to be copied
  [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, or named datatype.
  [in] | dst_name | Name to be assigned to the new copy
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lcopy() copies the link specified by `src_name` from the location specified by `src_loc_id` to the location specified by `dst_loc_id`. The new copy of the link is created with the name `dst_name`.

If `dst_loc_id` is a file identifier, `dst_name` will be interpreted relative to that file's root group.

The new link is created with the creation and access property lists specified by `lcpl_id` and `lapl_id`. The interpretation of `lcpl_id` is limited in the manner described in the next paragraph.

H5Lcopy() retains the creation time and the target of the original link. However, since the link may be renamed, the character encoding is specified in `lcpl_id` rather than in that of the original link. Other link creation properties are ignored.

If the link is a soft link, also known as a symbolic link, its target is interpreted relative to the location of the copy.

Several properties are available to govern the behavior of H5Lcopy(). These properties are set in the link creation and access property lists, `lcpl_id` and `lapl_id`, respectively. The property controlling creation of missing intermediate groups is set in the link creation property list with H5Pset_create_intermediate_group(); this function ignores any other properties in the link creation property list. Properties controlling character encoding, link traversals, and external link prefixes are set in the link access property list with H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix().

Note
  H5Lcopy() does not affect the object that the link points to.

Attention
  H5Lcopy() cannot copy hard links across files as a hard link is not valid without a target object; to copy objects from one file to another, see H5Ocopy().

See also
  H5Ocopy()

Since
  1.8.0

## ◆ H5Lcreate_external()

herr_t H5Lcreate_external | ( | const char * | file_name,
|  | const char * | obj_name,
|  | hid_t | link_loc_id,
|  | const char * | link_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates an external link, a soft link to an object in a different file.

Parameters

  [in] | file_name | Name of the target file containing the target object.
  [in] | obj_name | Path within the target file to the target object
  [in] | link_loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype.
  [in] | link_name | Name of the new link, relative to `link_loc_id`
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lcreate_external() creates a new external link. An external link is a soft link to an object in a different HDF5 file from the location of the link, i.e., to an external object.

`file_name` identifies the target file containing the target object; `obj_name` specifies the path of the target object within that file. `obj_name` must be an absolute pathname in `file_name`, i.e., it must start at the target file's root group, but it is not interpreted until an application attempts to traverse it.

`link_loc_id` and `link_name` specify the location and name, respectively, of the new link. `link_name` is interpreted relative to `link_loc_id`. If `link_name` begins with `/`, then it is interpreted as an absolute path in the file. The name of the created link will be the last element of the provided path. Prior elements in the path are used to locate the parent group of the new link.

`lcpl_id` is the link creation property list used in creating the new link.

`lapl_id` is the link access property list used in traversing the new link. Note that an external file opened by the traversal of an external link is always opened with the weak file close degree property setting, H5F_CLOSE_WEAK (see H5Pset_fclose_degree()); any file close degree property setting in `lapl_id` is ignored.

An external link behaves similarly to a soft link, and like a soft link in an HDF5 file, it may dangle: the target file and object need not exist at the time that the external link is created.

When the external link `link_name` is accessed, the library will search for the target file `file_name` as described below:

- If `file_name` is a relative pathname, the following steps are performed:
  - The library will get the prefix(es) set in the environment variable `HDF5_EXT_PREFIX` and will try to prepend each prefix to `file_name` to form a new `file_name`.
  - If the new `file_name` does not exist or if `HDF5_EXT_PREFIX` is not set, the library will get the prefix set via H5Pset_elink_prefix() and prepend it to `file_name` to form a new `file_name`.
  - If the new `file_name` does not exist or no prefix is being set by H5Pset_elink_prefix(), then the path of the file associated with `link_loc_id` is obtained. This path can be the absolute path or the current working directory plus the relative path of that file when it is created/opened. The library will prepend this path to `file_name` to form a new `file_name`.
  - If the new `file_name` does not exist, then the library will look for `file_name` and will return failure/success accordingly.
- If `file_name` is an absolute pathname, the library will first try to find `file_name`. If `file_name` does not exist, `file_name` is stripped of directory paths to form a new `file_name`. The search for the new `file_name` then follows the same steps as described above for a relative pathname. See examples below illustrating how target_file_name is stripped to form a new `file_name`.

Note that `file_name` is considered to be an absolute pathname when the following condition is true:

- For Unix, the first character of `file_name` is a slash (`/`). For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.
- For Windows, there are 6 cases:
  1. `file_name` is an absolute drive with an absolute pathname. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.
  2. `file_name` is an absolute pathname without specifying drive name. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.
  3. `file_name` is an absolute drive with a relative pathname. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `tmp\A.h5`.
  4. `file_name` is in UNC (Uniform Naming Convention) format with a server name, share name, and pathname. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.
  5. `file_name` is in Long UNC (Uniform Naming Convention) format with a server name, share name, and pathname. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.
  6. `file_name` is in Long UNC (Uniform Naming Convention) format with an absolute drive and an absolute pathname. For example, consider a `file_name` of `/tmp/A`.h5. If that target file does not exist, the new `file_name` after stripping will be `A.h5`.

The library opens the target file `file_name` with the file access property list that is set via H5Pset_elink_fapl() when the external link link_name is accessed. If no such property list is set, the library uses the file access property list associated with the file of `link_loc_id` to open the target file.

If an application requires additional control over file access flags or the file access property list, see H5Pset_elink_cb(); this function enables the use of an external link callback function as described in H5L_elink_traverse_t().

Attention
  A file close degree property setting (H5Pset_fclose_degree()) in the external link file access property list or in the external link callback function will be ignored. A file opened by means of traversing an external link is always opened with the weak file close degree property setting, H5F_CLOSE_WEAK .

See also
  H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_ud()

Since
  1.8.0

## ◆ H5Lcreate_hard()

herr_t H5Lcreate_hard | ( | hid_t | cur_loc,
|  | const char * | cur_name,
|  | hid_t | dst_loc,
|  | const char * | dst_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates a hard link to an object.

Parameters

  [in] | cur_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | cur_name | Name of the target object, which must already exist
  [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | dst_name | The name of the new link
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lcreate_hard() creates a new hard link to a pre-existing object in an HDF5 file.

`cur_loc` and `cur_name` specify the location and name, respectively, of the target object, i.e., the object that the new hard link points to. `dst_loc` and `dst_name` specify the location and name, respectively, of the new hard link.

`cur_name` and `dst_name` are interpreted relative to `cur_loc` and `dst_loc`, respectively. If a given name begins with `/`, then it will be interpreted as absolute path in the file. The names of the created links will be the last element of each provided path. Prior elements in each path are used to locate the parent groups of each new link. If `cur_loc` and `dst_loc` are the same location, the HDF5 macro H5L_SAME_LOC can be used for either parameter (but not both).

`lcpl_id` and `lapl_id` are the link creation and access property lists associated with the new link.

Note
  Hard and soft links are for use only if the target object is in the current file. If the desired target object is in a different file from the new link, an external link may be created with H5Lcreate_external().
  The HDF5 library keeps a count of all hard links pointing to an object; if the hard link count reaches zero (0), the object will be deleted from the file. Creating new hard links to an object will prevent it from being deleted if other links are removed. The library maintains no similar count for soft links and they can dangle.
  The new link may be one of many that point to that object.

Since
  1.8.0

## ◆ H5Lcreate_soft()

herr_t H5Lcreate_soft | ( | const char * | link_target,
|  | hid_t | link_loc_id,
|  | const char * | link_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates a soft link.

Parameters

  [in] | link_target | An HDF5 path name
  [in] | link_loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | link_name | The name of the new link
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lcreate_soft() creates a new soft link to an object in an HDF5 file.

`link_target` specifies the HDF5 path name the soft link contains. `link_target` can be an arbitrary HDF5 path name and is interpreted only at lookup time. This path may be absolute in the file or relative to `link_loc_id`.

`link_loc_id` and `link_name` specify the location and name, respectively, of the new soft link. `link_name` is interpreted as a path relative to `link_loc_id`, or an absolute path if it begins with `/`. The name of the created link will be the last element of the provided path. Prior elements in the path are used to locate the parent group of the new link.

If `link_loc_id` is a group identifier, the object pointed to by `link_name` will be accessed as a member of that group. If `link_loc_id` is a file identifier, the object will be accessed as a member of the file's root group.

`lcpl_id` and `lapl_id` are the link creation and access property lists associated with the new link.

For instance, if target_path is ``./foo, `link_loc_id` specifies ``./x/y/bar, and the name of the new link is `new_link`, then a subsequent request for ``./x/y/bar/new_link will return the same object as would be found at ``./foo.

Note
  H5Lcreate_soft() is for use only if the target object is in the current file. If the desired target object is in a different file from the new link, use H5Lcreate_external() to create an external link.
  Soft links and external links are also known as symbolic links as they use a name to point to an object; hard links employ an object's address in the file.
  Unlike hard links, a soft link in an HDF5 file is allowed to dangle, meaning that the target object need not exist at the time that the link is created.
  The HDF5 library does not keep a count of soft links as it does of hard links.
  The new link may be one of many that point to that object.

See also
  H5Lcreate_hard(), H5Lcreate_external()

Since
  1.8.0

## ◆ H5Lcreate_ud()

herr_t H5Lcreate_ud | ( | hid_t | link_loc_id,
|  | const char * | link_name,
|  | H5L_type_t | link_type,
|  | const void * | udata,
|  | size_t | udata_size,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates a link of a user-defined type.

Parameters

  [in] | link_loc_id | Location identifier
  [in] | link_name | Link name
  [in] | link_type | User-defined link class
  [in] | udata | User-supplied link information
  [in] | udata_size | Size of udata buffer
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lcreate_ud() creates a link of user-defined type `link_type` named `link_name` at the location specified in `link_loc_id` with user-specified data `udata`.

`link_name` is interpreted relative to `link_loc_id`. If `link_name` begins with `/`, then it will be interpreted as an absolute path in the file. The name of the created link will be the last element of the provided path. Prior elements in the path are used to locate the parent group of the new link.

Valid values for the link class of the new link, `link_type`, include H5L_TYPE_EXTERNAL and any user-defined link classes that have been registered with the library. See H5Lregister() for further information.

The format of the information pointed to by `udata` is defined by the user. `udata_size` specifies the size of the `udata` buffer. `udata` may be NULL if `udata_size` is zero (0).

The property lists specified by `lcpl_id` and `lapl_id` specify properties used to create and access the link.

Note
  The external link type, H5L_TYPE_EXTERNAL, included in the HDF5 library distribution, is implemented as a user-defined link type. This was done, in part, to provide a model for the implementation of other user-defined links.

Since
  1.8.0

## ◆ H5Ldelete()

herr_t H5Ldelete | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | lapl_id )

Removes a link from a group.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of the link to delete
  [in] | lapl_id | Link access property list identifier

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

H5Ldelete() removes the link specified by `name` from the location `loc_id`.

If the link being removed is a hard link, H5Ldelete() also decrements the link count for the object to which name points. Unless there is a duplicate hard link in that group, this action removes the object to which name points from the group that previously contained it.

Object headers keep track of how many hard links refer to an object; when the hard link count, also referred to as the reference count, reaches zero, the object can be removed from the file. The file space associated will then be released, i.e., identified in memory as freespace. Objects which are open are not removed until all identifiers to the object are closed.

Attention
  Exercise caution in the use of H5Ldelete(); if the link being removed is on the only path leading to an HDF5 object, that object may become permanently inaccessible in the file.

See also
  H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external()

Since
  1.8.0

## ◆ H5Ldelete_by_idx()

herr_t H5Ldelete_by_idx | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | hid_t | lapl_id )

Removes the n-th link in a group.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of subject group
  [in] | idx_type | Index or field which determines the order
  [in] | order | Order within field or index
  [in] | n | Link for which to retrieve information
  [in] | lapl_id | Link access property list identifier

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

H5Ldelete_by_idx() removes the n-th link in a group according to the specified order, `order`, in the specified index, `index`.

If `loc_id` specifies the group in which the link resides, `group_name` can be a dot (``.).

See also
  H5Ldelete()

Since
  1.8.0

## ◆ H5Lexists()

htri_t H5Lexists | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | lapl_id )

Determines whether a link with the specified name exists in a group.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Link name
  [in] | lapl_id | Link access property list identifier

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

H5Lexists() allows an application to determine whether the link `name` exists in the location specified by `loc_id`. The link may be of any type; only the presence of a link with that name is checked.

Note that H5Lexists() verifies only that the target link exists. If name includes either a relative path or an absolute path to the target link, intermediate steps along the path must be verified before the existence of the target link can be safely checked. If the path is not verified, and an intermediate element of the path does not exist, H5Lexists() will fail. The example in the next paragraph illustrates one step-by-step method for verifying the existence of a link with a relative or absolute path.

Example: Use the following steps to verify the existence of the link `datasetD` in the `group` group1/group2/softlink_to_group3/, where `group1` is a member of the group specified by `loc_id:`

1. First, use H5Lexists() to verify that the `group1` exists.
2. If `group1` exists, use H5Lexists() again, this time with name set to `group1/group2`, to verify that `group2` exists.
3. If `group2` exists, use H5Lexists() with name set to `group1/group2/softlink_to_group3` to verify that `softlink_to_group3` exists.
4. If `softlink_to_group3` exists, you can now safely use H5Lexists() with `name` set to `group1/group2/softlink_to_group3/datasetD` to verify that the target link, `datasetD`, exists.

If the link to be verified is specified with an absolute path, the same approach should be used, but starting with the first link in the file's root group. For instance, if `datasetD` were in `/group1/group2/softlink_to_group3`, the first call to H5Lexists() would have name set to `/group1`.

Note that this is an outline and does not include all the necessary details. Depending on circumstances, for example, you may need to verify that an intermediate link points to a group and that a soft link points to an existing target.

Note
  The behavior of H5Lexists() was changed in the 1.10 release in the case where the root group, `"/"`, is the name of the link. This change is described below:
  1. Let `file` denote a valid HDF5 file identifier, and let `lapl` denote a valid link access property list identifier. A call to H5Lexists() with arguments `file`, `"/"`, and `lapl` returns a positive value; in other words, H5Lexists(file, "/", lapl) returns a positive value. In the HDF5 1.8 release, this function returns 0.
  2. Let `root` denote a valid HDF5 group identifier that refers to the root group of an HDF5 file, and let `lapl` denote a valid link access property list identifier. A call to H5Lexists() with arguments c root, `"/"`, and `lapl` returns a positive value; in other words, H5Lexists(root, "/", lapl) returns a positive value. In the HDF5 1.8 release, this function returns 0.
  Note that the function accepts link names and path names. This is potentially misleading to callers, and we plan to separate the functionality for link names and path names in a future release.

Attention
  H5Lexists() checks the existence of only the final element in a relative or absolute path; it does not check any other path elements. The function will therefore fail when both of the following conditions exist:
  - `name` is not local to the group specified by `loc_id` or, if `loc_id` is something other than a group identifier, `name` is not local to the root group.
  - Any element of the relative path or absolute path in name, except the target link, does not exist.

Version
  1.10.0 Function behavior changed in this release. (See the note.)

Since
  1.8.0

## ◆ H5Lget_info1()

herr_t H5Lget_info1 | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5L_info1_t * | linfo,
|  | hid_t | lapl_id )

Returns information about a link.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Link name
  [out] | linfo | Buffer in which link information is returned
  [in] | lapl_id | Link access property list identifier

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

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Lget_info2() or the macro H5Lget_info().

H5Lget_info1() returns information about the specified link through the `linfo` argument.

The location identifier, `loc_id`, specifies the location of the link. A link name, `name`, interpreted relative to `loc_id`, specifies the link being queried.

`lapl_id` is the link access property list associated with the 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_info1() returns information about name in the data structure H5L_info1_t, which is described below and defined in H5Lpublic.h. This structure is returned in the buffer `linfo`.

typedef struct {
H5L_type_t type;
bool corder_valid;
int64_t corder;
H5T_cset_t cset;
union {
haddr_t address;
size_t val_size;
} u;
} H5L_info1_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 HDF5 path name with a null terminator.

Version
  1.12.0 Function was deprecated.
  1.8.2 Fortran subroutine added in this release.
  1.8.4 Fortran subroutine syntax changed in this release.

Since
  1.8.0

## ◆ H5Lget_info2()

herr_t H5Lget_info2 | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5L_info2_t * | linfo,
|  | hid_t | lapl_id )

Returns information about a link.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Link name
  [out] | linfo | Buffer in which link information is returned
  [in] | lapl_id | Link access property list identifier

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

H5Lget_info2() returns information about the specified link through the `linfo` argument.

The location identifier, `loc_id`, specifies the location of the link. A link name, `name`, interpreted relative to `loc_id`, specifies the link being queried.

`lapl_id` is the link access property list associated with the 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_info2() returns information about name in the data structure H5L_info2_t, which is described below and defined in H5Lpublic.h. This structure is returned in the buffer `linfo`.

typedef struct {
H5L_type_t type;
bool corder_valid;
int64_t corder;
H5T_cset_t cset;
union {
H5O_token_t token;
size_t val_size;
} u;
} H5L_info2_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.

`token` is the location that a hard link points to, and `val_size` is the size of a soft link or user-defined link value. H5O_token_t is used in the VOL layer. It is defined in H5public.h as:

typedef struct H5O_token_t {
uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;

If the link is a symbolic link, `val_size` will be the length of the link value, e.g., the length of the HDF5 path name with a null terminator.

Since
  1.12.0

## ◆ H5Lget_info_by_idx1()

herr_t H5Lget_info_by_idx1 | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5L_info1_t * | linfo,
|  | hid_t | lapl_id )

Retrieves metadata for a link in a group, according to the order within a field or index.

Parameters

  [in] | loc_id | Location identifier
  [in] | group_name | Group name
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Link position for which to retrieve information
  [out] | linfo | Buffer in which link information is returned
  [in] | lapl_id | Link access property list identifier

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

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Lget_info_by_idx2() and the macro H5Lget_info_by_idx().

H5Lget_info_by_idx1() returns the metadata for a link in a group according to a specified field or index and a specified order.

The link for which information is to be returned is specified by `idx_type`, `order`, and `n` as follows:

- `idx_type` specifies the field by which the links in `group_name` are ordered. The links may be indexed on this field, in which case operations seeking specific links are likely to complete more quickly.
- `order` specifies the order in which the links are to be referenced for the purposes of this function.
- `n` specifies the position of the subject link. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first link; if `n` is 5, the function will return the value of the sixth link; etc.

For example, assume that `idx_type`, `order`, and `n` are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in lexicographic order by their names. H5_ITER_DEC specifies that the list be traversed in reverse order, or in decremented order. And 5 specifies that this call to the function will return the metadata for the 6th link (`n` + 1) from the end.

See H5Literate1() for a list of valid values and further discussion regarding `idx_type` and `order`.

If `loc_id` specifies the group in which the link resides, `group_name` can be a dot (``.).

Version
  1.12.0 Function was renamed to H5Lget_index_by_idx1() and deprecated.
  1.8.4 Fortran subroutine syntax changed in this release.
  1.8.2 Fortran subroutine added in this release.

Since
  1.8.0

## ◆ H5Lget_info_by_idx2()

herr_t H5Lget_info_by_idx2 | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5L_info2_t * | linfo,
|  | hid_t | lapl_id )

Retrieves metadata for a link in a group, according to the order within a field or index.

Parameters

  [in] | loc_id | Location identifier
  [in] | group_name | Group name
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Link position for which to retrieve information
  [out] | linfo | Buffer in which link information is returned
  [in] | lapl_id | Link access property list identifier

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

H5Lget_info_by_idx2() returns the metadata for a link in a group according to a specified field or index and a specified order. The link for which information is to be returned is specified by `idx_type`, `order`, and `n` as follows:

- `idx_type` specifies the field by which the links in `group_name` are ordered. The links may be indexed on this field, in which case operations seeking specific links are likely to complete more quickly.
- `order` specifies the order in which the links are to be referenced for the purposes of this function.
- `n` specifies the position of the subject link. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first link; if `n` is 5, the function will return the value of the sixth link; etc.

For example, assume that `idx_type`, `order`, and `n` are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in lexicographic order by their names. H5_ITER_DEC specifies that the list be traversed in reverse order, or in decremented order. And 5 specifies that this call to the function will return the metadata for the 6th link (`n` + 1) from the end.

See H5Literate2() for a list of valid values and further discussion regarding `idx_type` and `order`.

If `loc_id` specifies the group in which the link resides, `group_name` can be a dot (``.).

Since
  1.12.0

See also
  H5Lget_info2()

## ◆ H5Lget_name_by_idx()

ssize_t H5Lget_name_by_idx | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | char * | name,
|  | size_t | size,
|  | hid_t | lapl_id )

Retrieves name of the n-th link in a group, according to the order within a specified field or index.

Parameters

  [in] | loc_id | Location identifier
  [in] | group_name | Group name
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Link position for which to retrieve information
  [out] | name | Buffer in which link name is returned
  [in] | size | Size in bytes of `name`
  [in] | lapl_id | Link access property list identifier

Returns
  Returns the size of the link name if successful; otherwise returns a negative value.

H5Lget_name_by_idx() retrieves the name of the n-th link in a group, according to the specified order, `order`, within a specified field or index, `idx_type`.

`idx_type` specifies the index that is used. Valid values include the following:

H5_INDEX_NAME | Lexicographic order on name
H5_INDEX_CRT_ORDER | Index on creation order

`order` specifies the order in which objects are inspected along the index specified in `idx_type`. Valid values include the following:

H5_ITER_INC | Increasing order
H5_ITER_DEC | Decreasing order
H5_ITER_NATIVE | Fastest available order

If `loc_id` specifies the group in which the link resides, `group_name` can be a dot (``.).

Up to `size` characters of the link name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the link name, which determines the required value of `size`, is unknown, a preliminary call to H5Lget_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 link name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Lget_name_by_idx() call, which will retrieve the actual link name.

Note
  Please note that in order for the specified index to correspond to the creation order index, `order` must be set to H5_ITER_INC or H5_ITER_DEC when calling H5Lget_name_by_idx().
  The index `n` passed to H5Lget_name_by_idx() is the index of the link within the link table, sorted according to `order` and `idx_type`. If order is H5_ITER_NATIVE, then the link table is not sorted, and it does not matter what `idx_type` is. Specifying H5_ITER_NATIVE does not guarantee any particular order, only that it remains consistent.

Since
  1.8.0

## ◆ H5Lget_val()

herr_t H5Lget_val | ( | hid_t | loc_id,
|  | const char * | name,
|  | void * | buf,
|  | size_t | size,
|  | hid_t | lapl_id )

Returns the value of a link.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Link name
  [out] | buf | The buffer to hold the link value
  [in] | size | Maximum number of bytes of link value to be returned
  [in] | lapl_id | Link access property list identifier

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

H5Lget_val() returns the value of link `name`. For symbolic links, this is the path to which the link points, including the null terminator. For external and user-defined links, it is the link buffer.

`size` is the size of `buf` and should be the size of the link value being returned. This size value can be determined through a call to H5Lget_info(); it is returned in the `val_size` field of the H5L_info_t `struct`.

If `size` is smaller than the size of the returned value, then the string stored in `buf` will be truncated to `size` bytes. For soft links, this means that the value will not be null terminated.

In the case of external links, the target file and object names are extracted from `buf` by calling H5Lunpack_elink_val().

The link class of link `name` can be determined with a call to H5Lget_info().

`lapl_id` specifies the link access property list associated with the 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()).

This function should be used only after H5Lget_info() has been called to verify that `name` is a symbolic link. This can be determined from the `link_type` field of the H5L_info_t `struct`.

Note
  This function will fail if called on a hard link.

See also
  H5Lget_val_by_idx()

Since
  1.8.0

## ◆ H5Lget_val_by_idx()

herr_t H5Lget_val_by_idx | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | void * | buf,
|  | size_t | size,
|  | hid_t | lapl_id )

Retrieves value of the n-th link in a group, according to the order within an index.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Group name
  [in] | idx_type | Type of index
  [in] | order | Order within field or index
  [in] | n | Link position for which to retrieve information
  [out] | buf | The buffer to hold the link value
  [in] | size | Maximum number of bytes of link value to be returned
  [in] | lapl_id | Link access property list identifier

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

H5Lget_val_by_idx() retrieves the value of the n-th link in a group, according to the specified order, `order`, within an index, `index`.

For soft links, the value is an HDF5 path name.

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.

`loc_id` specifies the location identifier of the group specified by `group_name`.

`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 link_val is specified in `size`. The size value can be determined through a call to H5Lget_info_by_idx(); it is returned in the `val_size` field of the H5L_info_t `struct`. If size is smaller than the size of the returned value, then the string stored in link_val will be truncated to size bytes. For soft links, this means that the value will not be null terminated.

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().

Note
  This function will fail if called on a hard link.

See also
  H5Lget_val()

Since
  1.8.0

## ◆ H5Lmove()

herr_t H5Lmove | ( | hid_t | src_loc,
|  | const char * | src_name,
|  | hid_t | dst_loc,
|  | const char * | dst_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Moves a link within an HDF5 file.

Parameters

  [in] | src_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | src_name | Original link name
  [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | dst_name | New link name
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Lmove() moves a link within an HDF5 file. The original link, `src_name`, is removed from `src_loc` and the new link, `dst_name`, is inserted at dst_loc. This change is accomplished as an atomic operation.

`src_loc` and `src_name` identify the original link. `src_loc` is the original location identifier; `src_name` is the path to the link and is interpreted relative to `src_loc`.

`dst_loc` and `dst_name` identify the new link. `dst_loc` is either a file or group identifier; `dst_name` is the path to the link and is interpreted relative to `dst_loc`.

`lcpl_id` and `lapl_id` are the link creation and link access property lists, respectively, associated with the new link, `dst_name`.

Through these property lists, several properties are available to govern the behavior of H5Lmove(). The property controlling creation of missing intermediate groups is set in the link creation property list with H5Pset_create_intermediate_group(); H5Lmove() ignores any other properties in the link creation property list. Properties controlling character encoding, link traversals, and external link prefixes are set in the link access property list with H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(), respectively.

Note
  Note that H5Lmove() does not modify the value of the link; the new link points to the same object as the original link pointed to. Furthermore, if the object pointed to by the original link was already open with a valid object identifier, that identifier will remain valid after the call to H5Lmove().

Attention
  Exercise care in moving links as it is possible to render data in a file inaccessible with H5Lmove(). If the link being moved is on the only path leading to an HDF5 object, that object may become permanently inaccessible in the file.

Since
  1.8.0

## ◆ H5Lunpack_elink_val()

herr_t H5Lunpack_elink_val | ( | const void * | ext_linkval,
|  | size_t | link_size,
|  | unsigned * | flags,
|  | const char ** | filename,
|  | const char ** | obj_path )

Decodes external link information.

Parameters

  [in] | ext_linkval | Buffer containing external link information
  [in] | link_size | Size, in bytes, of the `ext_linkval` buffer
  [out] | flags | External link flags, packed as a bitmap (Reserved as a bitmap for flags; no flags are currently defined, so the only valid value * is 0.)
  [out] | filename | Returned filename
  [out] | obj_path | Returned object path, relative to `filename`

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

H5Lunpack_elink_val() decodes the external link information returned by H5Lget_val() in the `ext_linkval` buffer.

`ext_linkval` should be the buffer set by H5Lget_val() and will consist of two NULL-terminated strings, the filename and object path, one after the other.

Given this buffer, H5Lunpack_elink_val() creates pointers to the filename and object path within the buffer and returns them in `filename` and `obj_path`, unless they are passed in as NULL.

H5Lunpack_elink_val() requires that `ext_linkval` contain a concatenated pair of null-terminated strings, so use of this function on a string that is not an external link `udata` buffer may result in a segmentation fault. This failure can be avoided by adhering to the following procedure:

1. Call H5Lget_info() to get the link type and the size of the link value.
3. Verify that the link is an external link, i.e., that its link type is H5L_TYPE_EXTERNAL.
4. Call H5Lget_val() to get the link value.
5. Call H5Lunpack_elink_val() to unpack that value.

Since
  1.8.0