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.