IN: Location identifier at which object is to be linked; may be a file, group, dataset, named datatype or attribute identifier
IN: Name of link to be created, relative tonew_loc_id
IN: Link creation property list identifier
IN: Link access property list identifier
H5O_LINK creates a new hard link to an object in an HDF5 file.
new_loc_idandnew_namespecify the location and name of the new link whileobject_ididentifies 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 withH5D_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.
lcplandlaplare 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 groupCwith the path/A/B01/Cbut may not know at run time whether the groupsAandB01exist. 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, theH5O_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.