diff options
author | mattjala <124107509+mattjala@users.noreply.github.com> | 2023-11-15 14:18:14 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-11-15 14:18:14 (GMT) |
commit | 07f7ae4991e138b1ba27b84df790a7ad56222921 (patch) | |
tree | a12e183f31c491f528c390cf91d91eab3ac85314 /src | |
parent | 61aef8d2bd69dfd6d655100ac8455184b6875459 (diff) | |
download | hdf5-07f7ae4991e138b1ba27b84df790a7ad56222921.zip hdf5-07f7ae4991e138b1ba27b84df790a7ad56222921.tar.gz hdf5-07f7ae4991e138b1ba27b84df790a7ad56222921.tar.bz2 |
Test and document path handling of H5Lcreate_* API (#3846)
* Document path handling of H5Lcreate_* API
* Document that link name is last part of path
* Test H5Lcreate path handling behavior
* State that absolute paths require forward slash
Diffstat (limited to 'src')
-rw-r--r-- | src/H5Lpublic.h | 27 |
1 files changed, 20 insertions, 7 deletions
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index 03b47c5..2bf3c53 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -260,9 +260,13 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const * location and name, respectively, of the new hard link. * * \p cur_name and \p dst_name are interpreted relative to \p cur_loc - * and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the - * same location, the HDF5 macro #H5L_SAME_LOC can be used for either - * parameter (but not both). + * and \p dst_loc, respectively. If a given name begins with \c /, + * then it will be interpreted as absolute path in the file. + * The names of the created links will be the last element of + * each provided path. Prior elements in each path are used to + * locate the parent groups of each new link. If \p cur_loc and + * \p dst_loc are the same location, the HDF5 macro + * #H5L_SAME_LOC can be used for either parameter (but not both). * * \p lcpl_id and \p lapl_id are the link creation and access property * lists associated with the new link. @@ -321,8 +325,10 @@ H5_DLL herr_t H5Lcreate_hard_async(hid_t cur_loc_id, const char *cur_name, hid_t * * \p link_loc_id and \p link_name specify the location and name, * respectively, of the new soft link. \p link_name is interpreted - * relative to \p link_loc_id and must contain only the name of the soft - * link; \p link_name may not contain any additional path elements. + * as a path relative to \p link_loc_id, or an absolute path if it + * begins with \c /. The name of the created link will be the last + * element of the provided path. Prior elements in the path are + * used to locate the parent group of the new link. * * If \p link_loc_id is a group identifier, the object pointed to by * \p link_name will be accessed as a member of that group. If @@ -1190,7 +1196,11 @@ H5_DLL herr_t H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t * named \p link_name at the location specified in \p link_loc_id with * user-specified data \p udata. * - * \p link_name is interpreted relative to \p link_loc_id. + * \p link_name is interpreted relative to \p link_loc_id. If + * \p link_name begins with \c /, then it will be interpreted as + * an absolute path in the file. The name of the created link + * will be the last element of the provided path. Prior elements + * in the path are used to locate the parent group of the new link. * * Valid values for the link class of the new link, \p link_type, * include #H5L_TYPE_EXTERNAL and any user-defined link classes that @@ -1307,7 +1317,10 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si * * \p link_loc_id and \p link_name specify the location and name, * respectively, of the new link. \p link_name is interpreted relative - * to \p link_loc_id. + * to \p link_loc_id. If \p link_name begins with \c /, then it is + * interpreted as an absolute path in the file. The name of the created + * link will be the last element of the provided path. Prior elements in + * the path are used to locate the parent group of the new link. * * \p lcpl_id is the link creation property list used in creating the * new link. |