- Created by Mike McGreevy, last modified by Barbara Jones on Apr 25, 2019
H5O_LINK
Creates a hard link to an object in an HDF5 file
Procedure:
H5O_LINK(object_id, new_loc_id, new_link_name, lcpl, lapl)
Signature:
herr_t H5Olink( hid_t object_id, hid_t new_loc_id, const char *new_link_name, hid_t lcpl, hid_t lapl )
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
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 :: lcpl_id
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id
Parameters:
hid_t object_id | IN: Object to be linked |
hid_t new_loc_id | IN: 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_id | IN: Link creation property list identifier |
hid_t lapl_id | IN: Link access property list identifier |
Description:
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:
Returns a non-negative value if successful; otherwise returns a negative value.
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 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.
History:
| Release | Change |
|---|---|
| 1.8.1 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
--- Last Modified: April 25, 2019 | 01:27 PM