Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.14.3
API Reference
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
+ Collaboration diagram for Links (H5L):

Modules

 Advanced Link Functions
 
 Link Traversal
 

Macros

#define H5Lget_info   H5Lget_info2
 
#define H5Lget_info_by_idx   H5Lget_info_by_idx2
 

Functions

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. More...
 
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. More...
 
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. More...
 
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. More...
 
herr_t H5Ldelete (hid_t loc_id, const char *name, hid_t lapl_id)
 Removes a link from a group. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
herr_t H5Lget_info2 (hid_t loc_id, const char *name, H5L_info2_t *linfo, hid_t lapl_id)
 Returns information about a link. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
herr_t H5Lget_info1 (hid_t loc_id, const char *name, H5L_info1_t *linfo, hid_t lapl_id)
 Returns information about a link. More...
 
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. More...
 

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

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_locLocation identifier. The identifier may be that of a file, group, dataset, or named datatype.
[in]src_nameName of the link to be copied
[in]dst_locLocation identifier. The identifier may be that of a file, group, dataset, or named datatype.
[in]dst_nameName to be assigned to the new copy
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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_nameName of the target file containing the target object.
[in]obj_namePath within the target file to the target object
[in]link_loc_idLocation identifier. The identifier may be that of a file, group, dataset, or named datatype.
[in]link_nameName of the new link, relative to link_loc_id
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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.

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_locLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]cur_nameName of the target object, which must already exist
[in]dst_locLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]dst_nameThe name of the new link
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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 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_targetAn HDF5 path name
[in]link_loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]link_nameThe name of the new link
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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 relative to link_loc_id and must contain only the name of the soft link; link_name may not contain any additional path elements.

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_idLocation identifier
[in]link_nameLink name
[in]link_typeUser-defined link class
[in]udataUser-supplied link information
[in]udata_sizeSize of udata buffer
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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.

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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the link to delete
[in]lapl_idLink 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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of subject group
[in]idx_typeIndex or field which determines the order
[in]orderOrder within field or index
[in]nLink for which to retrieve information
[in]lapl_idLink 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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameLink name
[in]lapl_idLink 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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameLink name
[out]linfoBuffer in which link information is returned
[in]lapl_idLink 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;
hbool_t corder_valid;
int64_t corder;
H5T_cset_t cset;
union {
haddr_t address;
size_t val_size;
} u;
H5L_type_t
Link class types.
Definition: H5Lpublic.h:63
H5T_cset_t
Definition: H5Tpublic.h:93
uint64_t haddr_t
Definition: H5public.h:325
bool hbool_t
Definition: H5public.h:249
Definition: H5Lpublic.h:1452

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

H5L_TYPE_HARDHard link
H5L_TYPE_SOFTSoft link
H5L_TYPE_EXTERNALExternal link
H5L_TYPE_ERRORError

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_ASCIIUS ASCII
H5T_CSET_UTF8UTF-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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameLink name
[out]linfoBuffer in which link information is returned
[in]lapl_idLink 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;
hbool_t corder_valid;
int64_t corder;
H5T_cset_t cset;
union {
H5O_token_t token;
size_t val_size;
} u;
Information struct for links.
Definition: H5Lpublic.h:87
Definition: H5public.h:400

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

H5L_TYPE_HARDHard link
H5L_TYPE_SOFTSoft link
H5L_TYPE_EXTERNALExternal link
H5L_TYPE_ERRORError

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_ASCIIUS ASCII
H5T_CSET_UTF8UTF-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 {
#define H5O_MAX_TOKEN_SIZE
Definition: H5public.h:391
uint8_t __data[(16)]
Definition: H5public.h:401

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_idLocation identifier
[in]group_nameGroup name
[in]idx_typeIndex type
[in]orderIteration order
[in]nLink position for which to retrieve information
[out]linfoBuffer in which link information is returned
[in]lapl_idLink 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().

H5get_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_idLocation identifier
[in]group_nameGroup name
[in]idx_typeIndex type
[in]orderIteration order
[in]nLink position for which to retrieve information
[out]linfoBuffer in which link information is returned
[in]lapl_idLink access property list identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5get_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_idLocation identifier
[in]group_nameGroup name
[in]idx_typeIndex type
[in]orderIteration order
[in]nLink position for which to retrieve information
[out]nameBuffer in which link name is returned
[in]sizeSize in bytes of name
[in]lapl_idLink access property list identifier
Returns
Returns the size of the link name if successful; otherwise returns a negative value.

H5get_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_NAMELexicographic order on name
H5_INDEX_CRT_ORDERIndex 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_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest available order

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

The size in bytes of name is specified in size. If size is unknown, it can be determined via an initial H5Lget_name_by_idx() call with name set to NULL; the function's return value will be the size of the 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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameLink name
[out]bufThe buffer to hold the link value
[in]sizeMaximum number of bytes of link value to be returned
[in]lapl_idLink 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_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameGroup name
[in]idx_typeType of index
[in]orderOrder within field or index
[in]nLink position for which to retrieve information
[out]bufThe buffer to hold the link value
[in]sizeMaximum number of bytes of link value to be returned
[in]lapl_idLink 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_locLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]src_nameOriginal link name
[in]dst_locLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]dst_nameNew link name
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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_linkvalBuffer containing external link information
[in]link_sizeSize, in bytes, of the ext_linkval buffer
[out]flagsExternal 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]filenameReturned filename
[out]obj_pathReturned 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.
  2. Verify that the link is an external link, i.e., that its link type is H5L_TYPE_EXTERNAL.
  3. Call H5Lget_val() to get the link value.
  4. Call H5Lunpack_elink_val() to unpack that value.
Since
1.8.0