Creates a hard link to an object in an HDF5 file


H5O_LINK(object_id, new_loc_id, new_link_name, lcpl, lapl)


<pre><code class="language-c">herr_t H5Olink( hid_t object_id, hid_t new_loc_id, const char *new_link_name, hid_t lcpl, hid_t lapl )</code></pre>

<pre><code class="language-fortran">SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name,  &
            hdferr, lcpl_id, lapl_id)
    INTEGER(HID_T)  , INTENT(IN)  :: object_id
    INTEGER(HID_T)  , INTENT(IN)  :: new_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: new_link_name
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id</code></pre>

hid_t object_idIN: Object to be linked
hid_t new_loc_idIN: Location identifier at which object is to be linked; may be a file, group, dataset, named datatype or attribute identifier
const char *new_link_name    IN: Name of link to be created, relative to new_loc_id
hid_t lcpl_idIN: Link creation property list identifier
hid_t lapl_idIN: Link access property list identifier


H5O_LINK 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.

H5O_LINK is designed for two purposes:

  • To create the first hard link to an object that has just been created with H5D_CREATE_ANON, H5G_CREATE_ANON, or H5T_COMMIT_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.


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


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 H5O_LINK call is mandatory if an object created with one of the H5*_CREATE_ANON functions (or with H5T_COMMIT_ANON) is to be retained in the file; without an H5O_LINK call, the object will not be linked into the HDF5 file structure and will be deleted when the file is closed.

Release    Change
1.8.1Fortran subroutine introduced in this release.
1.8.0Function introduced in this release.