Last modified: 23 August 2013
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 H5Dcreate_anon, H5Gcreate_anon, or 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

    See Also:
    H5Dcreate_anon
    H5Gcreate_anon
    H5Tcommit_anon

    History:
    Release     C
    1.8.1 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.