HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

H5L: Link Interface

Link API Functions

The Link interface, H5L, functions create and manipulate links in an HDF5 group. This interface includes functions that enable the creation and use of user-defined link classes.

The C Interfaces:
             
Alphabetical Listing
             

The Fortran Interface:
In general, each Fortran subroutine performs exactly the same task as the corresponding C function.
             


Last modified: 26 July 2011
Name: H5Lcopy
Signature:
herr_t H5Lcopy( hid_t src_loc_id, const char *src_name, hid_t dest_loc_id, const char *dest_name, hid_t lcpl_id, hid_t lapl_id )

Purpose:
Copies a link from one location to another.

Description:
H5Lcopy copies the link specified by src_name from the file or group specified by src_loc_id to the file or group specified by dest_loc_id. The new copy of the link is created with the name dest_name.

If dest_loc_id is a file identifier, dest_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 that specified in lcpl_id rather than 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.

H5Lcopy does not affect the object that the link points to.

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.

Parameters:
hid_t src_loc_id IN: Location identifier of the source link
const char *src_name IN: Name of the link to be copied
hid_t dest_loc_id IN: Location identifier specifying the destination of the copy
const char *dest_name     IN: Name to be assigned to the new copy
hid_t lcpl_id IN: Link creation property list identifier
hid_t lapl_id IN: Link access property list identifier

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

Fortran90 Interface: h5lcopy_f
SUBROUTINE h5lcopy_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, &
                     lcpl_id, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: src_loc_id 
                                   ! Location identifier of the source link
  CHARACTER(LEN=*), INTENT(IN) :: src_name   
                                   ! Name of the link to be copied
  INTEGER(HID_T), INTENT(IN) :: dest_loc_id 
                                   ! Location identifier specifying the 
                                   ! destination of the copy
  CHARACTER(LEN=*), INTENT(IN) :: dest_name 
                                   ! Name to be assigned to the new copy
  INTEGER, INTENT(OUT) :: hdferr   ! Error code: 
                                   ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id 
                                   ! Link creation property list identifier
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                   ! Link access property list identifier
END SUBROUTINE h5lcopy_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 18 June 2013
Name: H5Lcreate_external
Signature:
herr_t H5Lcreate_external( const char *target_file_name, const char *target_obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id )

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

Description:
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.

target_file_name identifies the target file containing the target object; target_obj_name specifies the path of the target object within that file. target_obj_name must be an absolute pathname in target_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 target_file_name as described below:

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

The library opens target file target_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.

Restriction: 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.

Parameters:
const char * target_file_name IN: Name of the target file containing the target object
const char *target_obj_name     IN: Path within the target file to the target object
hid_t link_loc_id IN: File or group identifier where the new link is to be created
const char * link_name IN: Name of the new link, relative to link_loc_id
hid_t lcpl_id IN: Link creation property list identifier
hid_t lapl_id IN: Link access property list identifier

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

Fortran90 Interface: h5lcreate_external_f
SUBROUTINE h5lcreate_external_f(file_name, obj_name, link_loc_id, link_name, &
	                        hdferr, lcpl_id, lapl_id) 
  IMPLICIT NONE
  CHARACTER(LEN=*), INTENT(IN) :: file_name  
                       ! Name of the file containing the target object. Neither 
                       ! the file nor the target object is required to exist. 
                       ! May be the file the link is being created in.
  CHARACTER(LEN=*), INTENT(IN) :: obj_name  
                       ! Name of the target object, which need not already exist.
  INTEGER(HID_T), INTENT(IN) :: link_loc_id 
                       ! The file or group identifier for the new link.
  CHARACTER(LEN=*), INTENT(IN) :: link_name 
                       ! The name of the new link.
  INTEGER, INTENT(OUT) :: hdferr        
                       ! Error code: 
                       ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id 
                       ! Link creation property list identifier.
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                       ! Link access property list identifier.
END SUBROUTINE h5lcreate_external_f
    

See Also:
H5Pset_elink_fapl,   H5Pset_elink_cb

H5L_elink_traverse_t

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 9 November 2009
Name: H5Lcreate_hard
Signature:
herr_t H5Lcreate_hard( hid_t obj_loc_id, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id )

Purpose:
Creates a hard link to an object.

Description:
H5Lcreate_hard creates a new hard link to a pre-existing object in an HDF5 file. The new link may be one of many that point to that object.

The target object must already exist in the file.

obj_loc_id and obj_name specify the location and name, respectively, of the target object, i.e., the object that the new hard link points to.

link_loc_id and link_name specify the location and name, respectively, of the new hard link.

obj_name and link_name are interpreted relative to obj_loc_id and link_loc_id, respectively.

If obj_loc_id and link_loc_id 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.

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.

Parameters:
hid_t obj_loc_id IN: The file or group identifier for the target object.
const char *obj_name     IN: Name of the target object, which must already exist.
hid_t link_loc_id IN: The file or group identifier for the new link.
const char * link_name IN: The name of the new link.
hid_t lcpl_id IN: Link creation property list identifier.
hid_t lapl_id IN: Link access property list identifier.

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

Fortran90 Interface: h5lcreate_hard_f
SUBROUTINE h5lcreate_hard_f(obj_loc_id, obj_name, link_loc_id, link_name, &
                            hdferr, lcpl_id, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: obj_loc_id  
                          ! The file or group identifier for the target object.
  CHARACTER(LEN=*), INTENT(IN) :: obj_name  
                          ! Name of the target object, which must already exist.
  INTEGER(HID_T), INTENT(IN) :: link_loc_id 
                          ! The file or group identifier for the new link.
  CHARACTER(LEN=*), INTENT(IN) :: link_name 
                          ! The name of the new link.
  INTEGER, INTENT(OUT) :: hdferr        
                          ! Error code: 
                          ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) ::   lcpl_id         
                          ! Link creation property list identifier.
  INTEGER(HID_T), OPTIONAL, INTENT(IN) ::   lapl_id         
                          ! Link access property list identifier.
END SUBROUTINE h5lcreate_hard_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 19 September 2013
Name: H5Lcreate_soft
Signature:
herr_t H5Lcreate_soft( const char *target_path, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id )

Purpose:
Creates a soft link to an object.

Description:
H5Lcreate_soft creates a new soft link to an object in an HDF5 file. The new link may be one of many that point to that object.

target_path specifies the path to the target object, i.e., the object that the new soft link points to. target_path can be anything and is interpreted at lookup time. This path may be absolute in the file or relative to link_loc_id.

link_loc_id must be a file or group identifier.

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 same the object as would be found at ./foo.

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.

Parameters:
const char *target_path     IN: Path to the target object, which is not required to exist.
hid_t link_loc_id IN: The file or group identifier for the new link.
const char * link_name IN: The name of the new link.
hid_t lcpl_id IN: Link creation property list identifier.
hid_t lapl_id IN: Link access property list identifier.

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

Fortran90 Interface: h5lcreate_soft_f
SUBROUTINE h5lcreate_soft_f(target_path, link_loc_id, link_name, hdferr, &
                            lcpl_id, lapl_id)
  IMPLICIT NONE
  CHARACTER(LEN=*), INTENT(IN) :: target_path
                                 ! Path to the target object, 
                                 ! which is not required to exist.
  INTEGER(HID_T), INTENT(IN) :: link_loc_id     
                                 ! The file or group identifier for the new link.
  CHARACTER(LEN=*), INTENT(IN) :: link_name       
                                 ! The name of the new link.
  INTEGER, INTENT(OUT) :: hdferr ! Error code: 
                                 ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
                                 ! Link creation property list identifier.
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
                                 ! Link access property list identifier.
END SUBROUTINE h5lcreate_soft_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 13 August 2009
Name: H5Lcreate_ud
Signature:
herr_t H5Lcreate_ud( hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const char *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id )

Purpose:
Creates a link of a user-defined type.

Description:
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.

Parameters:
hid_t link_loc_id IN: Link location identifier
const char *link_name     IN: Link name
H5L_type_t link_type IN: User-defined link class
const char *udata IN: User-supplied link information
size_t udata_size IN: Size of udata buffer
hid_t lcpl_id IN: Link creation property list identifier
hid_t lapl_id IN: Link access property list identifier

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 16 September 2014
Name: H5Ldelete
Signature:
herr_t H5Ldelete( hid_t loc_id, const char *name, hid_t lapl_id )

Purpose:
Removes a link from a group.

Description:
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.

Warning:
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.

Parameters:
hid_t loc_id IN: Identifier of the file or group containing the object.
const char *name     IN: Name of the link to delete.
hid_t lapl_id IN: Link access property list identifier.

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

Fortran90 Interface: h5ldelete_f
SUBROUTINE h5ldelete_f(loc_id, name, hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id  ! Identifier of the file or group 
                                        ! containing the object
  CHARACTER(LEN=*), INTENT(IN) :: name  ! Name of the link to delete
  INTEGER, INTENT(OUT) :: hdferr        ! Error code: 
                                        ! 0 on success and -1 on failure 
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                        ! Link access property list identifier
END SUBROUTINE h5ldelete_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Ldelete_by_idx
Signature:
herr_t H5Ldelete_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, hid_t lapl_id )

Purpose:
Removes the nth link in a group.

Description:
H5Ldelete_by_idx removes the nth 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 (.).

Parameters:
hid_t loc_id IN: File or group identifier specifying location of subject group
const char *group_name     IN: Name of subject group
H5_index_t index_field IN: Index or field which determines the order
H5_iter_order_t order IN: Order within field or index
hsize_t n IN: Link for which to retrieve information
hid_t lapl_id IN: Link access property list

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

Fortran90 Interface: h5ldelete_by_idx_f
SUBROUTINE h5ldelete_by_idx_f(loc_id, group_name, index_field, order, n, &
     hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id       
                           ! Identifer for object to which attribute is attached.
  CHARACTER(LEN=*), INTENT(IN) :: group_name 
                           ! Name of object, relative to location, 
                           ! from which attribute is to be removed
  INTEGER, INTENT(IN) :: index_field         
                           ! Type of index; Possible values are:
                           !    H5_INDEX_UNKNOWN_F   - Unknown index type
                           !    H5_INDEX_NAME_F      - Index on names
                           !    H5_INDEX_CRT_ORDER_F - Index on creation order
                           !    H5_INDEX_N_F	      - Number of indices defined
  INTEGER, INTENT(IN) :: order 
                           ! Order in which to iterate over index; 
                           ! Possible values are:
                           !    H5_ITER_UNKNOWN_F  - Unknown order
                           !    H5_ITER_INC_F      - Increasing order
                           !    H5_ITER_DEC_F      - Decreasing order
                           !    H5_ITER_NATIVE_F   - No particular order, 
                           !                         whatever is fastest
                           !    H5_ITER_N_F	   - Number of iteration orders
  INTEGER(HSIZE_T), INTENT(IN) :: n      
                           ! Offset within index 
  INTEGER, INTENT(OUT) :: hdferr         
                           ! Error code:
                           ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id     
                           ! Link access property list
END SUBROUTINE h5ldelete_by_idx_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 1 April 2016
Name: H5Lexists
Signature:
htri_t H5Lexists( hid_t loc_id, const char *name, hid_t lapl_id )

Purpose:
Determine whether a link with the specified name exists in a group.

Description:
H5Lexists allows an application to determine whether the link name exists in the group or file specified with 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 absloute 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:

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 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 on Behavior Change:
The behavior of H5Lexists was changed in the 1.10.0 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 HDF5 version 1.8.16, 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 ‘root’, “/”, and ‘lapl’ returns a positive value; in other words, H5Lexists(root, "/", lapl) returns a postive value. In HDF5 version 1.8.16, 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.

Parameters:
hid_t loc_id IN: Identifier of the file or group to query.
const char *name     IN: The name of the link to check.
hid_t lapl_id IN: Link access property list identifier.

Returns:
Returns a positive value if the link exists.
Returns 0 if the link does not exist.
Returns a negative value when the function fails and may return a negative value if the link does not exist. See “Failure Modes” below.

Failure Modes:
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:

Fortran90 Interface: h5lexists_f
SUBROUTINE h5lexists_f(loc_id, name, link_exists, hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier of file or group to query.
  CHARACTER(LEN=*), INTENT(IN) :: name ! Link name to check.
  LOGICAL, INTENT(OUT) :: link_exists  ! .TRUE. if exists, .FALSE. otherwise
  INTEGER, INTENT(OUT) :: hdferr       ! Error code:
                                       ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                       ! Link access property list identifier.
END SUBROUTINE h5lexists_f 
    

History:
Release     C
1.10.0 Function behavior changed in this release. See the “Note on Behavior Change” section above.
1.8.0 Function introduced in this release.

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

Purpose:
Returns information about a link.

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

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

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

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

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

In the above struct, type specifies the link class. Valid values include the following:
     H5L_TYPE_HARD Hard link
     H5L_TYPE_SOFT Soft link
     H5L_TYPE_EXTERNAL     External link
     H5L_TYPE_ERROR Error
There will be additional valid values if user-defined links have been registered.

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

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

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

cset specifies the character set in which the link name is encoded. Valid values include the following:
     H5T_CSET_ASCII US ASCII
     H5T_CSET_UTF8     UTF-8 Unicode encoding
This value is set with H5Pset_char_encoding.

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

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

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

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

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

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

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

Last modified: 11 November 2009
Name: H5Lget_info_by_idx
Signature:
herr_t H5Lget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5L_info_t *link_val, hid_t lapl_id )

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

Description:
H5Lget_info_by_idx 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 index_field, order, and n as follows:

For example, assume that index_field, order, and n are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in alpha-numeric 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 H5Literate for a list of valid values and further discussion regarding index_field and order.

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

Parameters:
hid_t loc_id IN: File or group identifier specifying location of subject group
const char *group_name     IN: Name of subject group
H5_index_t index_field IN: Index or field which determines the order
H5_iter_order_t order IN: Order within field or index
hsize_t n IN: Link for which to retrieve information
H5L_info_t *link_val OUT: Buffer in which link value is returned
hid_t lapl_id IN: Link access property list

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

Fortran90 Interface: h5lget_info_by_idx_f
SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
               link_type, f_corder_valid, corder, cset, address, val_size, &
               hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id 
                             ! File or group identifier specifying 
                             ! location of subject group  
  CHARACTER(LEN=*), INTENT(IN) :: group_name 
                             ! Name of subject group
  INTEGER, INTENT(IN) :: index_field   
                             ! Index/field which determines the order
                             !   H5_INDEX_UNKNOWN_F   - Unknown index type
                             !   H5_INDEX_NAME_F      - Index on names
                             !   H5_INDEX_CRT_ORDER_F - Index on creation order
                             !   H5_INDEX_N_F	      - Number of indices defined
  INTEGER, INTENT(IN) :: order        
                             ! Order in which to iterate over index; 
                             ! Possible values are:
                             !    H5_ITER_UNKNOWN_F  - Unknown order
                             !    H5_ITER_INC_F      - Increasing order
                             !    H5_ITER_DEC_F      - Decreasing order
                             !    H5_ITER_NATIVE_F   - No particular order, 
                             !                         whatever is fastest
  INTEGER(HSIZE_T), INTENT(IN) :: n   
                             ! Attribute’s position in index
  INTEGER, INTENT(OUT) :: link_type 
                             ! Specifies the link class:
     	                     !   H5L_TYPE_HARD_F      - Hard link
     	                     !   H5L_TYPE_SOFT_F      - Soft link
     	                     !   H5L_TYPE_EXTERNAL_F  - External link
     	                     !   H5L_TYPE_ERROR_F     - Error
  LOGICAL, INTENT(OUT) :: f_corder_valid 
                             ! Indicates whether the creation order data is 
                             ! valid for this attribute 
  INTEGER, INTENT(OUT) :: corder 
                             ! Is a positive integer containing the creation 
                             ! order of the attribute
  INTEGER, INTENT(OUT) :: cset 
                             ! Indicates the character set used for the 
                             ! attribute’s name
  INTEGER(HADDR_T), INTENT(OUT) :: address  
                             ! If the link is a hard link, address specifies the 
                             ! file address that the link points to
  INTEGER(SIZE_T), INTENT(OUT) :: val_size 
                             ! If the link is a symbolic link, val_size will be 
                             ! the length of the link value, i.e. the length of 
                             ! the name of the pointed-to object with a null 
                             ! terminator.
  INTEGER, INTENT(OUT) :: hdferr       
                             ! Error code:
                             ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id  
                             ! Link access property list
END SUBROUTINE h5lget_info_by_idx_f  
    

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

Last modified: 3 April 2013
Name: H5Lget_name_by_idx
Signature:
ssize_t H5Lget_name_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id )

Purpose:
Retrieves name of the nth link in a group, according to the order within a specified field or index.

Description:
H5Lget_name_by_idx retrieves the name of the nth link in a group, according to the specified order, order, within a specified field or index, index_field.

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:

Parameters:
hid_t loc_id IN: File or group identifier specifying location of subject group
const char *group_name     IN: Name of subject group
H5_index_t index_field IN: Index or field which determines the order
H5_iter_order_t order IN: Order within field or index
hsize_t n IN: Link for which to retrieve information
char *name OUT: Buffer in which link value is returned
size_t size IN: Size in bytes of name
hid_t lapl_id IN: Link access property list

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

Fortran90 Interface: h5lget_info_by_idx_f
SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
     f_corder_valid, corder, cset, data_size, hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id  
                    ! File/group identifier specifying location of subject group
  CHARACTER(LEN=*), INTENT(IN) :: group_name 
                    ! Name of subject group
  INTEGER, INTENT(IN) :: index_field  
                    ! Index or field which determines the order
                    !    H5_INDEX_UNKNOWN_F   - Unknown index type
                    !    H5_INDEX_NAME_F      - Index on names
                    !    H5_INDEX_CRT_ORDER_F - Index on creation order
                    !    H5_INDEX_N_F         - Number of indices defined
  INTEGER, INTENT(IN) :: order        
                    ! Order in which to iterate over index; Possible values are:
                    !    H5_ITER_UNKNOWN_F  - Unknown order
                    !    H5_ITER_INC_F      - Increasing order
                    !    H5_ITER_DEC_F      - Decreasing order
                    !    H5_ITER_NATIVE_F   - No particular order
                    !                         whatever is fastest
    
  INTEGER(HSIZE_T), INTENT(IN) :: n   
                    ! Attribute’s position in index
  LOGICAL, INTENT(OUT) :: f_corder_valid 
                    ! Indicates whether the creation order data is valid for 
                    ! this attribute 
  INTEGER, INTENT(OUT) :: corder 
                    ! Is a positive integer containing the creation order of the
                    ! attribute
  INTEGER, INTENT(OUT) :: cset 
                    ! Indicates the character set used for the attribute’s name
  INTEGER(HSIZE_T), INTENT(OUT) :: data_size   
                    ! Indicates the size, in the number of characters, of 
                    ! the attribute
  INTEGER, INTENT(OUT) :: hdferr       
                    ! Error code:
                    ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id  
                    ! Link access property list
END SUBROUTINE h5lget_info_by_idx_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 9 November 2009
Name: H5Lget_val
Signature:
herr_t H5Lget_val( hid_t link_loc_id, const char *link_name, void *linkval_buff, size_t size, hid_t lapl_id )

Purpose:
Returns the value of a symbolic link.

Description:
H5Lget_val returns the link value of the link link_name.

The parameter link_loc_id is a file or group identifier.

link_name identifies a symbolic link and is defined relative to link_loc_id. Symbolic links include soft and external links and some user-defined links. This function is not for use with hard links.

The link value is returned in the buffer linkval_buff. For soft 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 linkval_buff 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 linkval_buff 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 linkval_buff 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 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 link_name is a symbolic link. This can be deteremined from the link_type field of the H5L_info_t struct.

Parameters:
hid_t link_loc_id IN: File or group identifier.
const char *link_name     IN: Link whose value is to be returned.
void *linkval_buff OUT: The buffer to hold the returned link value.
size_t size IN: Maximum number of characters of link value to be returned.
hid_t lapl_id IN: List access property list identifier.

Returns:
Returns a non-negative value, with the link value in linkval_buff, if successful. Otherwise returns a negative value.

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

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

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

Description:
H5Lget_val_by_idx retrieves the value of the nth link in a group, according to the specified order, order, within an index, index.

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

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

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

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

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

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Lis_registered
Signature:
htri_t H5Lis_registered( H5L_type_t link_cls_id )

Purpose:
Determines whether a class of user-defined links is registered.

Description:
H5Lis_registered tests whether a user-defined link class is currently registered, either by the HDF5 Library or by the user through the use of H5Lregister.

A link class must be registered to create new links of that type or to traverse exisitng links of that type.

Parameters:
H5L_type_t link_cls_id     IN: User-defined link class identifier

Returns:
Returns a positive value if the link class has been registered and zero if it is unregistered. Otherwise returns a negative value; this may mean that the identifier is not a valid user-defined class identifier.

Fortran90 Interface: H5Lis_registered_f
SUBROUTINE H5Lis_registered_f(link_cls_id, registered, hdferr)
  IMPLICIT NONE
  INTEGER, INTENT(IN) :: link_cls_id  ! User-defined link class identifier
  LOGICAL, INTENT(OUT) :: registered  ! .TRUE.  - if the link class is registered
                                      ! .FALSE. - if it is unregistered
  INTEGER, INTENT(OUT) :: hdferr      ! Error code:
                                      ! 0 on success and -1 on failure
END SUBROUTINE H5Lis_registered_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 26 September 2014
Name: H5Literate
Signature:
herr_t H5Literate( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data )

Purpose:
Iterates through links in a group.

Description:
H5Literate iterates through the links in a group, specified by group_id, in the order of the specified index, index_type, using a user-defined callback routine op. H5Literate does not recursively follow links into subgroups of the specified group.

Three parameters are used to manage progress of the iteration: index_type, order, and idx.

index_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Valid values include the following:
     H5_INDEX_NAME Alpha-numeric index on name
     H5_INDEX_CRT_ORDER     Index on creation order

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
     H5_ITER_INC Increasing order
     H5_ITER_DEC Decreasing order
     H5_ITER_NATIVE     Fastest available order

idx allows an interrupted iteration to be resumed; it is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.

The op callback function, the related H5L_info_t struct, and the effect of the callback function’s return value on the application are described in H5Lvisit.

op_data is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the op callback function’s op_data parameter.

As mentioned above, H5Literate is not recursive. In particular, if a member of group_id is found to be a group, call it subgroup_a, H5Literate does not examine the members of subgroup_a. When recursive iteration is required, the application can do either of the following:

H5Literate assumes that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the function’s behavior is undefined. Note, however, that objects pointed to by the links can be modified.

H5Literate is the same as deprecated function H5Giterate, except that H5Giterate always proceeded in alphanumeric order.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:
hid_t group_id IN: Identifier specifying subject group
H5_index_t index_type     IN: Type of index which determines the order
H5_iter_order_t order IN: Order within index
hsize_t *idx IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted
H5L_iterate_t op IN: Callback function passing data regarding the link to the calling application
void *op_data IN: User-defined pointer to data required by the application for its processing of the link

Returns:
On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Fortran2003 Interface: h5literate_f
Signature:

  SUBROUTINE h5literate_f(group_id, index_type, order, idx, &
            op, op_data, return_value, hdferr)
    INTEGER(HID_T)  , INTENT(IN)    :: group_id
    INTEGER         , INTENT(IN)    :: index_type
    INTEGER         , INTENT(IN)    :: order
    INTEGER(HSIZE_T), INTENT(INOUT) :: idx
    TYPE(C_FUNPTR)  , INTENT(IN)    :: op
    TYPE(C_PTR)     , INTENT(IN)    :: op_data
    INTEGER         , INTENT(OUT)   :: return_value
    INTEGER         , INTENT(OUT)   :: hdferr

Inputs:

  group_id   - Identifier specifying subject group
  index_type - Type of index which determines the order:
                H5_INDEX_NAME_F      - Alpha-numeric index on name
                H5_INDEX_CRT_ORDER_F - Index on creation order
  order      - Order within index:
                H5_ITER_INC_F    - Increasing order
                H5_ITER_DEC_F    - Decreasing order
                H5_ITER_NATIVE_F - Fastest available order
  idx        - IN: Iteration position at which to start
  op         - Callback function passing data regarding the link to the 
               calling application
  op_data    - User-defined pointer to data required by the application 
               for its processing of the link

Outputs:

  idx          - OUT: Position at which an interrupted iteration may 
                          be restarted
  return_value - Success: The return value of the first operator that
                          returns non-zero, or zero if all members were
                          processed with no operator returning non-zero.

                 Failure: Negative if something goes wrong within the
                          library, or the negative value returned by one
                          of the operators.

  hdferr       - Returns 0 if successful and -1 if fails

Programming Note for Fortran Developers:

The integer type of the callback function must match the C integer type. Therefore, for portability, all Fortran callback functions used by h5literate_f should be declared as INTEGER(KIND=C_INT).

History:
Release     Change
1.8.8 Fortran subroutine added.
1.8.0 C function introduced.

Last modified: 28 March 2016
Name: H5Literate_by_name
Signature:
herr_t H5Literate_by_name( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data, hid_t lapl_id )

Purpose:
Iterates through links in a group.

Description:
H5Literate_by_name iterates through the links in a group, specified by loc_id and group_name, in the order of the specified index, index_type, using a user-defined callback routine op. H5Literate_by_name does not recursively follow links into subgroups of the specified group.

index_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecesary, so the iteration may begin more quickly. Valid values include the following:
     H5_INDEX_NAME Alpha-numeric index on name
     H5_INDEX_CRT_ORDER     Index on creation order

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
     H5_ITER_INC Increasing order
     H5_ITER_DEC Decreasing order
     H5_ITER_NATIVE     Fastest available order

idx allows an interrupted iteration to be resumed; it is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.

H5Literate_by_name is not recursive. In particular, if a member of group_name is found to be a group, call it subgroup_a, H5Literate_by_name does not examine the members of subgroup_a. When recursive iteration is required, the application must handle the recursion, explicitly calling H5Literate_by_name on discovered subgroups.

H5Literate_by_name assumes that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the function’s behavior is undefined. Note, however, that objects pointed to by the links can be modified.

H5Literate_by_name is the same as H5Giterate, except that H5Giterate always proceeds in alphanumeric order.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:
hid_t loc_id IN: File or group identifier specifying location of subject group
const char *group_name     IN: Name of subject group
H5_index_t index_type IN: Type of index which determines the order
H5_iter_order_t order IN: Order within index
hsize_t *idx IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted
H5L_iterate_t op IN: Callback function passing data regarding the link to the calling application
void *op_data IN: User-defined pointer to data required by the application for its processing of the link
hid_t lapl_id IN: Link access property list

Returns:
On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Fortran2003 Interface: h5literate_by_name_f
Signature:

  SUBROUTINE h5literate_by_name_f(loc_id, group_name, index_type, &
            order, idx, op, op_data, return_value, hdferr, lapl_id)
    INTEGER(HID_T), INTENT(IN) :: loc_id
    CHARACTER(LEN=*) :: group_name 
    INTEGER, INTENT(IN) :: index_type
    INTEGER, INTENT(IN) :: order
    INTEGER(HSIZE_T), INTENT(INOUT) :: idx

    TYPE(C_FUNPTR):: op  
    TYPE(C_PTR)   :: op_data

    INTEGER, INTENT(OUT) :: return_value

    INTEGER, INTENT(OUT) :: hdferr
    INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id

Inputs:

  loc_id     - File or group identifier specifying location of subject group
  group_name - Name of subject group
  index_type - Type of index which determines the order:
                H5_INDEX_NAME_F      - Alpha-numeric index on name
                H5_INDEX_CRT_ORDER_F - Index on creation order
  order      - Order within index:
                H5_ITER_INC_F    - Increasing order
                H5_ITER_DEC_F    - Decreasing order
                H5_ITER_NATIVE_F - Fastest available order
  idx        - IN: Iteration position at which to start
  op         - Callback function passing data regarding the link to the 
               calling application
  op_data    - User-defined pointer to data required by the application for 
               its processing of the link

Outputs:

  idx          - OUT: Position at which an interrupted iteration 
                          may be restarted
  return_value - Success: The return value of the first operator that
                          returns non-zero, or zero if all members were
                          processed with no operator returning non-zero.

                 Failure: Negative if something goes wrong within the
                          library, or the negative value returned by one
                          of the operators.

  hdferr        - Returns 0 if successful and -1 if fails

Optional parameters:

  lapl_id    - Link access property list

Programming Note for Fortran Developers:

The integer type of the callback function must match the C integer type. Therefore, for portability, all Fortran callback functions used by h5literate_by_name_f should be declared as INTEGER(KIND=C_INT).

History:
Release     Change
1.8.8 Fortran subroutine added.
1.8.0 C function introduced.

Last modified: 2 July 2012
Name: H5Lmove
Signature:
herr_t H5Lmove( hid_t src_loc_id, const char *src_name, hid_t dest_loc_id, const char *dest_name, hid_t lcpl_id, hid_t lapl_id )

Purpose:
Moves a link within an HDF5 file.

Description:
H5Lmove moves a link within an HDF5 file. The original link, src_name, is removed from src_loc_id and the new link, dest_name, is inserted at dest_loc_id. This change is accomplished as an atomic operation.

src_loc_id and src_name identify the original link. src_loc_id is either a file or group identifier; src_name is the path to the link and is interpreted relative to src_loc_id.

dest_loc_id and dest_name identify the new link. dest_loc_id is either a file or group identifier; dest_name is the path to the link and is interpreted relative to dest_loc_id.

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.

lcpl_id and lapl_id are the link creation and link access property lists, respectively, associated with the new link, dest_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.

Warning:
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.

Parameters:
hid_t src_loc_id IN: Original file or group identifier.
const char *src_name     IN: Original link name.
hid_t dest_loc_id IN: Destination file or group identifier.
const char *dest_name IN: New link name.
hid_t lcpl_id IN: Link creation property list identifier to be associated with the new link.
hid_t lapl_id IN: Link access property list identifier to be associated with the new link.

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

Fortran90 Interface: h5lmove_f
SUBROUTINE h5lmove_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, &
    lcpl_id, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: src_loc_id  
                                        ! Original file or group identifier.
  CHARACTER(LEN=*), INTENT(IN) :: src_name  
                                        ! Original link name.
  INTEGER(HID_T), INTENT(IN) :: dest_loc_id 
                                        ! Destination file or group identifier.
  CHARACTER(LEN=*), INTENT(IN) :: dest_name 
                                        ! New link name.
  INTEGER(HID_T), INTENT(OUT) :: hdferr ! Error code:
                                        ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id 
                                        ! Link creation property list identifier 
                                        ! to be associated with the new link.
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                        ! Link access property list identifier 
                                        ! to be associated with the new link.
END SUBROUTINE h5lmove_f
    

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 21 August 2013
Name: H5Lregister
Signature:
herr_t H5Lregister( const H5L_class_t * link_class )

Purpose:
Registers a user-defined link class or changes behavior of an existing class.

Description:
H5Lregister registers a class of user-defined links, or changes the behavior of an existing class.

link_class is a pointer to a buffer containing a copy of the H5L_class_t struct. This struct is defined in H5Lpublic.h as follows:

  typedef struct H5L_class_t {
      int version;                    /* Version number of this struct  */
      H5L_type_t class_id;            /* Link class identifier          */
      const char *comment;            /* Comment for debugging          */
      H5L_create_func_t create_func;  /* Callback during link creation  */
      H5L_move_func_t move_func;      /* Callback after moving link     */
      H5L_copy_func_t copy_func;      /* Callback after copying link    */
      H5L_traverse_func_t trav_func;  /* The main traversal function    */
      H5L_delete_func_t del_func;     /* Callback for link deletion     */
      H5L_query_func_t query_func;    /* Callback for queries           */
  } H5L_class_t;
      

The class definition passed with link_class must include at least the following: Remaining struct members are optional and may be passed as NULL.

The link class passed in class_id must be in the user-definable range between H5L_TYPE_UD_MIN and H5L_TYPE_UD_MAX (see the “Link Class Identifiers...” table below) and will override any existing link class with that identifier.

As distributed, valid values of class_id used in HDF5 include the following (defined in H5Lpublic.h):
     H5L_TYPE_HARD Hard link
     H5L_TYPE_SOFT Soft link
     H5L_TYPE_EXTERNAL     External link
The hard and soft link class identifiers cannot be modified or reassigned, but the external link class is implemented as an example in the user-definable link class identifier range. H5Lregister is used to register additional link classes. It could also be used to modify the behavior of the external link class, though that is not recommended.

The following table summarizes existing link types and values and the reserved and user-definable link class identifier value ranges.

Link Class Identifiers or Value Ranges,
Descriptions, and Class Names
Link class identifier
or Value range
   Description    Link class or
other label

0  to  63   Reserved range    
64  to  255   User-definable range    

64    Minimum user-defined value   H5L_TYPE_UD_MIN 
64    External link   H5L_TYPE_EXTERNAL 
255    Maximum user-defined value   H5L_TYPE_UD_MAX 
255    Maximum value   H5L_TYPE_MAX 

-1    Error   H5L_TYPE_ERROR 

Note that HDF5 internally registers user-defined link classes only by the numeric value of the link class identifier. An application, on the other hand, will generally use a name for a user-defined class, if for no other purpose than as a variable name. Assume, for example, that a complex link type is registered with the link class identifier 73 and that the code includes the following assignment:
     H5L_TYPE_COMPLEX_A = 73
The application can refer to the link class with a term, H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing the code, while HDF5 recognizes it by the more cryptic numeric identifier, 73.

Critical Notes:
Important details and considerations include the following:

Parameters:
const H5L_class_t *link_class     IN: Pointer to a buffer containing the struct describing the user-defined link class

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

Fortran90 Interface:
None.

Registration with The HDF Group:
There are sometimes reasons to take a broader approach to registering a user-defined link class than just invoking H5Lregister. For example:

In such cases, you are encouraged to register that link class with The HDF Group’s Helpdesk (contact). The HDF Group maintains a registry of known user-defined link classes and tracks the selected link class identifiers. This registry is intended to reduce the risk of collisions between class_id values and to help coordinate the use of specialized link classes.

See Also:
H5Lis_registered

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 11 January 2010
Name: H5Lunpack_elink_val
Signature:
herr_t H5Lunpack_elink_val( char *ext_linkval, size_t link_size, unsigned *flags, const char **filename, const char **obj_path )

Purpose:
Decodes external link information.

Description:
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.

Parameters:
const char *ext_linkval     IN: Buffer containing external link information
size_t link_size IN: Size, in bytes, of the ext_linkval buffer
unsigned *flags OUT: 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.)
const char **filename OUT: Returned filename
const char **obj_path OUT: Returned object path, relative to filename

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Lunregister
Signature:
herr_t H5Lunregister( H5L_type_t link_cls_id )

Purpose:
Unregisters a class of user-defined links.

Description:
H5Lunregister unregisters a class of user-defined links, preventing them from being traversed, queried, moved, etc.

A link class can be re-registered using H5Lregister.

Parameters:
H5L_type_t link_cls_id     IN: User-defined link class identifier

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 August 2012
Name: H5Lvisit
Signature:
herr_t H5Lvisit( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data )

Purpose:
Recursively visits all links starting from a specified group.

Description:
H5Lvisit is a recursive iteration function to visit all links in and below a group in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those links or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate.

The group serving as the root of the iteration is specified by its group identifier, group_id.

Two parameters are used to establish the iteration: index_type and order.

index_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecesary, so the iteration may begin more quickly. Valid values include the following:
     H5_INDEX_NAME Alpha-numeric index on name
     H5_INDEX_CRT_ORDER     Index on creation order

Note that the index type passed in index_type is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
     H5_ITER_INC Increasing order
     H5_ITER_DEC Decreasing order
     H5_ITER_NATIVE     Fastest available order

The protoype of the callback function op is as follows (as defined in the source code file H5Lpublic.h):

herr_t (*H5L_iterate_t)( hid_t g_id, const char *name, const H5L_info_t *info, void *op_data)

The parameters of this callback function have the following values or meanings:
     g_id Group that serves as root of the iteration; same value as the H5Lvisit group_id parameter
     name Name of link, relative to g_id, being examined at current step of the iteration
     info H5L_info_t struct containing information regarding that link
     op_data     User-defined pointer to data required by the application in processing the link; a pass-through of the op_data pointer provided with the H5Lvisit function call

The H5L_info_t struct is defined (in H5Lpublic.h) as follows:

    typedef struct {
        H5L_type_t     type;         /* Type of link                   */
        hbool_t        corder_valid; /* Indicates whether creation     */
                                     /* order is valid                 */
        int64_t        corder;       /* Creation order                 */
        H5T_cset_t     cset;         /* Character set of link name     */
        union {
            haddr_t    address;      /* Address hard link points to    */
            size_t     val_size;     /* Size of soft link or           */
                                     /* user-defined link value        */
        } u;
    } H5L_info_t;

The possible return values from the callback function, and the effect of each, are as follows:

The H5Lvisit op_data parameter is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the op callback function’s op_data parameter.
 

H5Lvisit and H5Ovisit are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:
hid_t group_id IN: Identifier of the group at which the recursive iteration begins.
H5_index_t index_type IN: Type of index; valid values include:
         H5_INDEX_NAME
         H5_INDEX_CRT_ORDER
H5_iter_order_t order     IN: Order in which index is traversed; valid values include:
         H5_ITER_DEC
         H5_ITER_INC
         H5_ITER_NATIVE
H5L_iterate_t op IN: Callback function passing data regarding the link to the calling application
void *op_data IN: User-defined pointer to data required by the application for its processing of the link

Returns:
On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 August 2012
Name: H5Lvisit_by_name
Signature:
herr_t H5Lvisit_by_name( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id )

Purpose:
Recursively visits all links starting from a specified group.

Description:
H5Lvisit_by_name is a recursive iteration function to visit all links in and below a group in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those links or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate.

The group serving as the root of the iteration is specified by the loc_id / group_name parameter pair. loc_id specifies a file or group; group_name specifies either a group in the file (with an absolute name based in the file’s root group) or a group relative to loc_id. If loc_id fully specifies the group that is to serve as the root of the iteration, group_name should be '.' (a dot). (Note that when loc_id fully specifies the the group that is to serve as the root of the iteration, the user may wish to consider using H5Lvisit instead of H5Lvisit_by_name.)

Two parameters are used to establish the iteration: index_type and order.

index_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecesary, so the iteration may begin more quickly. Valid values include the following:
     H5_INDEX_NAME Alpha-numeric index on name
     H5_INDEX_CRT_ORDER     Index on creation order

Note that the index type passed in index_type is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
     H5_ITER_INC Increasing order
     H5_ITER_DEC Decreasing order
     H5_ITER_NATIVE     Fastest available order

The op callback funtion, the related H5L_info_t struct, and the effect that the callback function’s return value has on the application are described in H5Lvisit.

The H5Lvisit_by_name op_data parameter is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the callback function’s op_data parameter.

lapl_id is a link access property list. 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).
 

H5Lvisit_by_name and H5Ovisit_by_name are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:
hid_t loc_id IN: Identifier of a file or group
const char *name IN: Name of the group, generally relative to loc_id, that will serve as root of the iteration
H5_index_t index_type IN: Type of index; valid values include:
         H5_INDEX_NAME
         H5_INDEX_CRT_ORDER
H5_iter_order_t order     IN: Order in which index is traversed; valid values include:
         H5_ITER_DEC
         H5_ITER_INC
         H5_ITER_NATIVE
H5L_iterate_t op IN: Callback function passing data regarding the link to the calling application
void *op_data IN: User-defined pointer to data required by the application for its processing of the link
hid_t lapl_id IN: Link access property list identifier

Returns:
On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

The HDF Group Help Desk:
Describes HDF5 Release 1.10.0
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois