Name: H5Olink
Signature:
herr_t H5Olink( hid_t object_id, hid_t new_loc_id, const char *new_link_name, hid_t lcpl, hid_t lapl )

Purpose:
Creates a hard link to an object in an HDF5 file.

Description:
H5Olink creates a new hard link to an object in an HDF5 file.

new_loc_id and new_name specify the location and name of the new link while object_id identifies the object that the link points to.

H5Olink is designed for two purposes:
    
  • To create the first hard link to an object that has just been created with one of the H5*create_anon functions or with H5Tcommit_anon.
  •     
  • To add additional structure to an existing file so that, for example, an object can be shared among multiple groups.
  • lcpl and lapl are the link creation and access property lists associated with the new link.

    Parameters:
    hid_t object_id IN: Object to be linked.
    hid_t new_loc_id IN: File or group identifier specifying location at which object is to be linked.
    const char *new_link_name     IN: Name of link to be created, relative to new_loc_id.
    hid_t lcpl_id IN: Link creation property list identifier.
    hid_t lapl_id IN: Link access property list identifier.

    Example:
    To create a new link to an object while simultaneously creating missing intermediate groups:
    Suppose that an application must create the group C with the path /A/B01/C but may not know at run time whether the groups A and B01 exist. The following code ensures that those groups are created if they are missing:
        hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);   /* Creates a link creation
                                                       * property list (LCPL).    */
        int   status  = H5Pset_create_intermediate_group(lcpl_id, TRUE);
                                               /* Sets "create missing intermediate
                                                * groups" property in that LCPL.  */
        hid_t gid     = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
                                               /* Creates a group without linking 
                                                * it into the file structure.     */
        status        = H5Olink(obj_id, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
                                               /* Links group into file structure.*/
    

    Note that unless the object is intended to be temporary, the H5Olink call is mandatory if an object created with one of the H5*create_anon functions (or with H5Tcommit_anon) is to be retained in the file; without an H5Olink call, the object will not be linked into the HDF5 file structure and will be deleted when the file is closed.

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

    Fortran90 Interface: h5olink_f
    SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name, hdferr, &
                         lcpl_id, lapl_id)
      IMPLICIT NONE
      INTEGER(HID_T), INTENT(IN) :: object_id  
                                      ! Object to be linked
      INTEGER(HID_T), INTENT(IN) :: new_loc_id 
                                      ! File or group identifier specifying 
                                      ! location at which object is to be linked.
      CHARACTER(LEN=*), INTENT(IN) :: new_link_name 
                                      ! Name of link to be created, 
                                      ! relative to new_loc_id.
      INTEGER, INTENT(OUT) :: hdferr  ! Error code 		
                                      !   Success:  0
                                      !   Failure: -1  
      INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id 
                                      ! Link creation property list identifier.  
      INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                      ! Link creation property list identifier.
    END SUBROUTINE h5olink_f
        

    History:
    Release     C
    1.8.0 Function introduced in this release.