 |
HDF5 2.0.0.258fa78
API Reference
|
|
HDF5 2.0.0.258fa78
API Reference
|
Use the functions in this module to manage HDF5 links and link types.
Modules | |
| Advanced Link Functions | |
| Link Traversal | |
Macros | |
| #define | H5Lget_info H5Lget_info2 |
| #define | H5Lget_info_by_idx H5Lget_info_by_idx2 |
Functions | |
| herr_t | H5Lmove (hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id) |
| Moves a link within an HDF5 file. | |
| herr_t | H5Lcopy (hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id) |
| Creates an identical copy of a link with the same creation time and target. The new link can have a different name and be in a different location than the original. | |
| herr_t | H5Lcreate_hard (hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id) |
| Creates a hard link to an object. | |
| herr_t | H5Lcreate_soft (const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id) |
| Creates a soft link. | |
| herr_t | H5Ldelete (hid_t loc_id, const char *name, hid_t lapl_id) |
| Removes a link from a group. | |
| herr_t | H5Ldelete_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id) |
| Removes the n-th link in a group. | |
| herr_t | H5Lget_val (hid_t loc_id, const char *name, void *buf, size_t size, hid_t lapl_id) |
| Returns the value of a link. | |
| herr_t | H5Lget_val_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, void *buf, size_t size, hid_t lapl_id) |
| Retrieves value of the n-th link in a group, according to the order within an index. | |
| htri_t | H5Lexists (hid_t loc_id, const char *name, hid_t lapl_id) |
| Determines whether a link with the specified name exists in a group. | |
| herr_t | H5Lget_info2 (hid_t loc_id, const char *name, H5L_info2_t *linfo, hid_t lapl_id) |
| Returns information about a link. | |
| herr_t | H5Lget_info_by_idx2 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id) |
| Retrieves metadata for a link in a group, according to the order within a field or index. | |
| ssize_t | H5Lget_name_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id) |
| Retrieves name of the n-th link in a group, according to the order within a specified field or index. | |
| herr_t | H5Lcreate_ud (hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id) |
| Creates a link of a user-defined type. | |
| herr_t | H5Lunpack_elink_val (const void *ext_linkval, size_t link_size, unsigned *flags, const char **filename, const char **obj_path) |
| Decodes external link information. | |
| herr_t | H5Lcreate_external (const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id) |
| Creates an external link, a soft link to an object in a different file. | |
| herr_t | H5Lget_info1 (hid_t loc_id, const char *name, H5L_info1_t *linfo, hid_t lapl_id) |
| Returns information about a link. | |
| herr_t | H5Lget_info_by_idx1 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info1_t *linfo, hid_t lapl_id) |
| Retrieves metadata for a link in a group, according to the order within a field or index. | |
| #define H5Lget_info H5Lget_info2 |
H5Lget_info() is a macro that is mapped to either H5Lget_info1() or H5Lget_info2().
| #define H5Lget_info_by_idx H5Lget_info_by_idx2 |
H5Lget_info_by_idx() is a macro that is mapped to either H5Lget_info_by_idx1() or H5Lget_info_by_idx2().
| herr_t H5Lcopy | ( | hid_t | src_loc, |
| const char * | src_name, | ||
| hid_t | dst_loc, | ||
| const char * | dst_name, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates an identical copy of a link with the same creation time and target. The new link can have a different name and be in a different location than the original.
| [in] | src_loc | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | src_name | Name of the link to be copied |
| [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | dst_name | Name to be assigned to the new copy |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lcopy() copies the link specified by src_name from the location specified by src_loc_id to the location specified by dst_loc_id. The new copy of the link is created with the name dst_name.
If dst_loc_id is a file identifier, dst_name will be interpreted relative to that file's root group.
The new link is created with the creation and access property lists specified by lcpl_id and lapl_id. The interpretation of lcpl_id is limited in the manner described in the next paragraph.
H5Lcopy() retains the creation time and the target of the original link. However, since the link may be renamed, the character encoding is specified in lcpl_id rather than in that of the original link. Other link creation properties are ignored.
If the link is a soft link, also known as a symbolic link, its target is interpreted relative to the location of the copy.
Several properties are available to govern the behavior of H5Lcopy(). These properties are set in the link creation and access property lists, lcpl_id and lapl_id, respectively. The property controlling creation of missing intermediate groups is set in the link creation property list with H5Pset_create_intermediate_group(); this function ignores any other properties in the link creation property list. Properties controlling character encoding, link traversals, and external link prefixes are set in the link access property list with H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix().
| herr_t H5Lcreate_external | ( | const char * | file_name, |
| const char * | obj_name, | ||
| hid_t | link_loc_id, | ||
| const char * | link_name, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates an external link, a soft link to an object in a different file.
| [in] | file_name | Name of the target file containing the target object. |
| [in] | obj_name | Path within the target file to the target object |
| [in] | link_loc_id | Location identifier. The identifier may be that of a file, group, dataset, or named datatype. |
| [in] | link_name | Name of the new link, relative to link_loc_id |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lcreate_external() creates a new external link. An external link is a soft link to an object in a different HDF5 file from the location of the link, i.e., to an external object.
file_name identifies the target file containing the target object; obj_name specifies the path of the target object within that file. obj_name must be an absolute pathname in file_name, i.e., it must start at the target file's root group, but it is not interpreted until an application attempts to traverse it.
link_loc_id and link_name specify the location and name, respectively, of the new link. link_name is interpreted relative to link_loc_id. If link_name begins with /, 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.
lcpl_id is the link creation property list used in creating the new link.
lapl_id is the link access property list used in traversing the new link. Note that an external file opened by the traversal of an external link is always opened with the weak file close degree property setting, H5F_CLOSE_WEAK (see H5Pset_fclose_degree()); any file close degree property setting in lapl_id is ignored.
An external link behaves similarly to a soft link, and like a soft link in an HDF5 file, it may dangle: the target file and object need not exist at the time that the external link is created.
When the external link link_name is accessed, the library will search for the target file file_name as described below:
file_name is a relative pathname, the following steps are performed:HDF5_EXT_PREFIX and will try to prepend each prefix to file_name to form a new file_name.file_name does not exist or if HDF5_EXT_PREFIX is not set, the library will get the prefix set via H5Pset_elink_prefix() and prepend it to file_name to form a new file_name.file_name does not exist or no prefix is being set by H5Pset_elink_prefix(), then the path of the file associated with link_loc_id is obtained. This path can be the absolute path or the current working directory plus the relative path of that file when it is created/opened. The library will prepend this path to file_name to form a new file_name.file_name does not exist, then the library will look for file_name and will return failure/success accordingly.file_name is an absolute pathname, the library will first try to find file_name. If file_name does not exist, file_name is stripped of directory paths to form a new file_name. The search for the new file_name then follows the same steps as described above for a relative pathname. See examples below illustrating how target_file_name is stripped to form a new file_name.Note that file_name is considered to be an absolute pathname when the following condition is true:
file_name is a slash (/). For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.file_name is an absolute drive with an absolute pathname. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.file_name is an absolute pathname without specifying drive name. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.file_name is an absolute drive with a relative pathname. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be tmp\A.h5.file_name is in UNC (Uniform Naming Convention) format with a server name, share name, and pathname. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.file_name is in Long UNC (Uniform Naming Convention) format with a server name, share name, and pathname. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.file_name is in Long UNC (Uniform Naming Convention) format with an absolute drive and an absolute pathname. For example, consider a file_name of /tmp/A.h5. If that target file does not exist, the new file_name after stripping will be A.h5.The library opens the target file file_name with the file access property list that is set via H5Pset_elink_fapl() when the external link link_name is accessed. If no such property list is set, the library uses the file access property list associated with the file of link_loc_id to open the target file.
If an application requires additional control over file access flags or the file access property list, see H5Pset_elink_cb(); this function enables the use of an external link callback function as described in H5L_elink_traverse_t().
| herr_t H5Lcreate_hard | ( | hid_t | cur_loc, |
| const char * | cur_name, | ||
| hid_t | dst_loc, | ||
| const char * | dst_name, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates a hard link to an object.
| [in] | cur_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | cur_name | Name of the target object, which must already exist |
| [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | dst_name | The name of the new link |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lcreate_hard() creates a new hard link to a pre-existing object in an HDF5 file.
cur_loc and cur_name specify the location and name, respectively, of the target object, i.e., the object that the new hard link points to. dst_loc and dst_name specify the location and name, respectively, of the new hard link.
cur_name and dst_name are interpreted relative to cur_loc and dst_loc, respectively. If a given name begins with /, 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 cur_loc and dst_loc are the same location, the HDF5 macro H5L_SAME_LOC can be used for either parameter (but not both).
lcpl_id and lapl_id are the link creation and access property lists associated with the new link.
| herr_t H5Lcreate_soft | ( | const char * | link_target, |
| hid_t | link_loc_id, | ||
| const char * | link_name, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates a soft link.
| [in] | link_target | An HDF5 path name |
| [in] | link_loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | link_name | The name of the new link |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lcreate_soft() creates a new soft link to an object in an HDF5 file.
link_target specifies the HDF5 path name the soft link contains. link_target can be an arbitrary HDF5 path name and is interpreted only at lookup time. This path may be absolute in the file or relative to link_loc_id.
link_loc_id and link_name specify the location and name, respectively, of the new soft link. link_name is interpreted as a path relative to link_loc_id, or an absolute path if it begins with /. 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 link_loc_id is a group identifier, the object pointed to by link_name will be accessed as a member of that group. If link_loc_id is a file identifier, the object will be accessed as a member of the file's root group.
lcpl_id and lapl_id are the link creation and access property lists associated with the new link.
For instance, if target_path is ./foo, link_loc_id specifies ./x/y/bar, and the name of the new link is new_link, then a subsequent request for ./x/y/bar/new_link will return the same object as would be found at ./foo.
| herr_t H5Lcreate_ud | ( | hid_t | link_loc_id, |
| const char * | link_name, | ||
| H5L_type_t | link_type, | ||
| const void * | udata, | ||
| size_t | udata_size, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Creates a link of a user-defined type.
| [in] | link_loc_id | Location identifier |
| [in] | link_name | Link name |
| [in] | link_type | User-defined link class |
| [in] | udata | User-supplied link information |
| [in] | udata_size | Size of udata buffer |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lcreate_ud() creates a link of user-defined type link_type named link_name at the location specified in link_loc_id with user-specified data udata.
link_name is interpreted relative to link_loc_id. If link_name begins with /, 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, link_type, include H5L_TYPE_EXTERNAL and any user-defined link classes that have been registered with the library. See H5Lregister() for further information.
The format of the information pointed to by udata is defined by the user. udata_size specifies the size of the udata buffer. udata may be NULL if udata_size is zero (0).
The property lists specified by lcpl_id and lapl_id specify properties used to create and access the link.
Removes a link from a group.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the link to delete |
| [in] | lapl_id | Link access property list identifier |
H5Ldelete() removes the link specified by name from the location loc_id.
If the link being removed is a hard link, H5Ldelete() also decrements the link count for the object to which name points. Unless there is a duplicate hard link in that group, this action removes the object to which name points from the group that previously contained it.
Object headers keep track of how many hard links refer to an object; when the hard link count, also referred to as the reference count, reaches zero, the object can be removed from the file. The file space associated will then be released, i.e., identified in memory as freespace. Objects which are open are not removed until all identifiers to the object are closed.
| herr_t H5Ldelete_by_idx | ( | hid_t | loc_id, |
| const char * | group_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| hid_t | lapl_id | ||
| ) |
Removes the n-th link in a group.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | group_name | Name of subject group |
| [in] | idx_type | Index or field which determines the order |
| [in] | order | Order within field or index |
| [in] | n | Link for which to retrieve information |
| [in] | lapl_id | Link access property list identifier |
H5Ldelete_by_idx() removes the n-th link in a group according to the specified order, order, in the specified index, index.
If loc_id specifies the group in which the link resides, group_name can be a dot (.).
Determines whether a link with the specified name exists in a group.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Link name |
| [in] | lapl_id | Link access property list identifier |
H5Lexists() allows an application to determine whether the link name exists in the location specified by loc_id. The link may be of any type; only the presence of a link with that name is checked.
Note that H5Lexists() verifies only that the target link exists. If name includes either a relative path or an absolute path to the target link, intermediate steps along the path must be verified before the existence of the target link can be safely checked. If the path is not verified, and an intermediate element of the path does not exist, H5Lexists() will fail. The example in the next paragraph illustrates one step-by-step method for verifying the existence of a link with a relative or absolute path.
Example: Use the following steps to verify the existence of the link datasetD in the group group1/group2/softlink_to_group3/, where group1 is a member of the group specified by loc_id:
group1 exists.group1 exists, use H5Lexists() again, this time with name set to group1/group2, to verify that group2 exists.group2 exists, use H5Lexists() with name set to group1/group2/softlink_to_group3 to verify that softlink_to_group3 exists.softlink_to_group3 exists, you can now safely use H5Lexists() with name set to group1/group2/softlink_to_group3/datasetD to verify that the target link, datasetD, exists.If the link to be verified is specified with an absolute path, the same approach should be used, but starting with the first link in the file's root group. For instance, if datasetD were in /group1/group2/softlink_to_group3, the first call to H5Lexists() would have name set to /group1.
Note that this is an outline and does not include all the necessary details. Depending on circumstances, for example, you may need to verify that an intermediate link points to a group and that a soft link points to an existing target.
"/", is the name of the link. This change is described below: file denote a valid HDF5 file identifier, and let lapl denote a valid link access property list identifier. A call to H5Lexists() with arguments file, "/", and lapl returns a positive value; in other words, H5Lexists(file, "/", lapl) returns a positive value. In the HDF5 1.8 release, this function returns 0. root denote a valid HDF5 group identifier that refers to the root group of an HDF5 file, and let lapl denote a valid link access property list identifier. A call to H5Lexists() with arguments c root, "/", and lapl returns a positive value; in other words, H5Lexists(root, "/", lapl) returns a positive value. In the HDF5 1.8 release, this function returns 0. name is not local to the group specified by loc_id or, if loc_id is something other than a group identifier, name is not local to the root group.| herr_t H5Lget_info1 | ( | hid_t | loc_id, |
| const char * | name, | ||
| H5L_info1_t * | linfo, | ||
| hid_t | lapl_id | ||
| ) |
Returns information about a link.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Link name |
| [out] | linfo | Buffer in which link information is returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_info1() returns information about the specified link through the linfo argument.
The location identifier, loc_id, specifies the location of the link. A link name, name, interpreted relative to loc_id, specifies the link being queried.
lapl_id is the link access property list associated with the link name. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).
H5Lget_info1() returns information about name in the data structure H5L_info1_t, which is described below and defined in H5Lpublic.h. This structure is returned in the buffer linfo.
In the above struct, type specifies the link class. Valid values include the following:
| H5L_TYPE_HARD | Hard link |
| H5L_TYPE_SOFT | Soft link |
| H5L_TYPE_EXTERNAL | External link |
| H5L_TYPE_ERROR | Error |
There will be additional valid values if user-defined links have been registered.
corder specifies the link's creation order position while corder_valid indicates whether the value in corder is valid.
If corder_valid is true, the value in corder is known to be valid; if corder_valid is false, the value in corder is presumed to be invalid;
corder starts at zero (0) and is incremented by one (1) as new links are created. But higher-numbered entries are not adjusted when a lower-numbered link is deleted; the deleted link's creation order position is simply left vacant. In such situations, the value of corder for the last link created will be larger than the number of links remaining in the group.
cset specifies the character set in which the link name is encoded. Valid values include the following:
| H5T_CSET_ASCII | US ASCII |
| H5T_CSET_UTF8 | UTF-8 Unicode encoding |
This value is set with H5Pset_char_encoding.
address and val_size are returned for hard and symbolic links, respectively. Symbolic links include soft and external links and some user-defined links.
If the link is a hard link, address specifies the file address that the link points to.
If the link is a symbolic link, val_size will be the length of the link value, e.g., the length of the HDF5 path name with a null terminator.
| herr_t H5Lget_info2 | ( | hid_t | loc_id, |
| const char * | name, | ||
| H5L_info2_t * | linfo, | ||
| hid_t | lapl_id | ||
| ) |
Returns information about a link.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Link name |
| [out] | linfo | Buffer in which link information is returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_info2() returns information about the specified link through the linfo argument.
The location identifier, loc_id, specifies the location of the link. A link name, name, interpreted relative to loc_id, specifies the link being queried.
lapl_id is the link access property list associated with the link name. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).
H5Lget_info2() returns information about name in the data structure H5L_info2_t, which is described below and defined in H5Lpublic.h. This structure is returned in the buffer linfo.
In the above struct, type specifies the link class. Valid values include the following:
| H5L_TYPE_HARD | Hard link |
| H5L_TYPE_SOFT | Soft link |
| H5L_TYPE_EXTERNAL | External link |
| H5L_TYPE_ERROR | Error |
There will be additional valid values if user-defined links have been registered.
corder specifies the link's creation order position, while corder_valid indicates whether the value in corder is valid.
If corder_valid is true, the value in corder is known to be valid; if corder_valid is false, the value in corder is presumed to be invalid; corder starts at zero (0) and is incremented by one (1) as new links are created. But higher-numbered entries are not adjusted when a lower-numbered link is deleted; the deleted link's creation order position is simply left vacant. In such situations, the value of corder for the last link created will be larger than the number of links remaining in the group.
cset specifies the character set in which the link name is encoded. Valid values include the following:
| H5T_CSET_ASCII | US ASCII |
| H5T_CSET_UTF8 | UTF-8 Unicode encoding |
This value is set with H5Pset_char_encoding.
token is the location that a hard link points to, and val_size is the size of a soft link or user-defined link value. H5O_token_t is used in the VOL layer. It is defined in H5public.h as:
If the link is a symbolic link, val_size will be the length of the link value, e.g., the length of the HDF5 path name with a null terminator.
| herr_t H5Lget_info_by_idx1 | ( | hid_t | loc_id, |
| const char * | group_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| H5L_info1_t * | linfo, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves metadata for a link in a group, according to the order within a field or index.
| [in] | loc_id | Location identifier |
| [in] | group_name | Group name |
| [in] | idx_type | Index type |
| [in] | order | Iteration order |
| [in] | n | Link position for which to retrieve information |
| [out] | linfo | Buffer in which link information is returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_info_by_idx1() returns the metadata for a link in a group according to a specified field or index and a specified order.
The link for which information is to be returned is specified by idx_type, order, and n as follows:
idx_type specifies the field by which the links in group_name are ordered. The links may be indexed on this field, in which case operations seeking specific links are likely to complete more quickly.order specifies the order in which the links are to be referenced for the purposes of this function.n specifies the position of the subject link. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first link; if n is 5, the function will return the value of the sixth link; etc.For example, assume that idx_type, order, and n are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in lexicographic order by their names. H5_ITER_DEC specifies that the list be traversed in reverse order, or in decremented order. And 5 specifies that this call to the function will return the metadata for the 6th link (n + 1) from the end.
See H5Literate1() for a list of valid values and further discussion regarding idx_type and order.
If loc_id specifies the group in which the link resides, group_name can be a dot (.).
| herr_t H5Lget_info_by_idx2 | ( | hid_t | loc_id, |
| const char * | group_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| H5L_info2_t * | linfo, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves metadata for a link in a group, according to the order within a field or index.
| [in] | loc_id | Location identifier |
| [in] | group_name | Group name |
| [in] | idx_type | Index type |
| [in] | order | Iteration order |
| [in] | n | Link position for which to retrieve information |
| [out] | linfo | Buffer in which link information is returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_info_by_idx2() returns the metadata for a link in a group according to a specified field or index and a specified order. The link for which information is to be returned is specified by idx_type, order, and n as follows:
idx_type specifies the field by which the links in group_name are ordered. The links may be indexed on this field, in which case operations seeking specific links are likely to complete more quickly.order specifies the order in which the links are to be referenced for the purposes of this function.n specifies the position of the subject link. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first link; if n is 5, the function will return the value of the sixth link; etc.For example, assume that idx_type, order, and n are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in lexicographic order by their names. H5_ITER_DEC specifies that the list be traversed in reverse order, or in decremented order. And 5 specifies that this call to the function will return the metadata for the 6th link (n + 1) from the end.
See H5Literate2() for a list of valid values and further discussion regarding idx_type and order.
If loc_id specifies the group in which the link resides, group_name can be a dot (.).
| ssize_t H5Lget_name_by_idx | ( | hid_t | loc_id, |
| const char * | group_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| char * | name, | ||
| size_t | size, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves name of the n-th link in a group, according to the order within a specified field or index.
| [in] | loc_id | Location identifier |
| [in] | group_name | Group name |
| [in] | idx_type | Index type |
| [in] | order | Iteration order |
| [in] | n | Link position for which to retrieve information |
| [out] | name | Buffer in which link name is returned |
| [in] | size | Size in bytes of name |
| [in] | lapl_id | Link access property list identifier |
H5Lget_name_by_idx() retrieves the name of the n-th link in a group, according to the specified order, order, within a specified field or index, idx_type.
idx_type specifies the index that is used. Valid values include the following:
| H5_INDEX_NAME | Lexicographic order on name |
| H5_INDEX_CRT_ORDER | Index on creation order |
order specifies the order in which objects are inspected along the index specified in idx_type. Valid values include the following:
| H5_ITER_INC | Increasing order |
| H5_ITER_DEC | Decreasing order |
| H5_ITER_NATIVE | Fastest available order |
If loc_id specifies the group in which the link resides, group_name can be a dot (.).
Up to size characters of the link name are returned in name; additional characters, if any, are not returned to the user application.
If the length of the link name, which determines the required value of size, is unknown, a preliminary call to H5Lget_name_by_idx() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the link name. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Lget_name_by_idx() call, which will retrieve the actual link name.
order must be set to H5_ITER_INC or H5_ITER_DEC when calling H5Lget_name_by_idx(). n passed to H5Lget_name_by_idx() is the index of the link within the link table, sorted according to order and idx_type. If order is H5_ITER_NATIVE, then the link table is not sorted, and it does not matter what idx_type is. Specifying H5_ITER_NATIVE does not guarantee any particular order, only that it remains consistent.Returns the value of a link.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Link name |
| [out] | buf | The buffer to hold the link value |
| [in] | size | Maximum number of bytes of link value to be returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_val() returns the value of link name. For symbolic links, this is the path to which the link points, including the null terminator. For external and user-defined links, it is the link buffer.
size is the size of buf and should be the size of the link value being returned. This size value can be determined through a call to H5Lget_info(); it is returned in the val_size field of the H5L_info_t struct.
If size is smaller than the size of the returned value, then the string stored in buf will be truncated to size bytes. For soft links, this means that the value will not be null terminated.
In the case of external links, the target file and object names are extracted from buf by calling H5Lunpack_elink_val().
The link class of link name can be determined with a call to H5Lget_info().
lapl_id specifies the link access property list associated with the link name. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).
This function should be used only after H5Lget_info() has been called to verify that name is a symbolic link. This can be determined from the link_type field of the H5L_info_t struct.
| herr_t H5Lget_val_by_idx | ( | hid_t | loc_id, |
| const char * | group_name, | ||
| H5_index_t | idx_type, | ||
| H5_iter_order_t | order, | ||
| hsize_t | n, | ||
| void * | buf, | ||
| size_t | size, | ||
| hid_t | lapl_id | ||
| ) |
Retrieves value of the n-th link in a group, according to the order within an index.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | group_name | Group name |
| [in] | idx_type | Type of index |
| [in] | order | Order within field or index |
| [in] | n | Link position for which to retrieve information |
| [out] | buf | The buffer to hold the link value |
| [in] | size | Maximum number of bytes of link value to be returned |
| [in] | lapl_id | Link access property list identifier |
H5Lget_val_by_idx() retrieves the value of the n-th link in a group, according to the specified order, order, within an index, index.
For soft links, the value is an HDF5 path name.
For external links, this is a compound value containing file and path name information; to use this external link information, it must first be decoded with H5Lunpack_elink_val()
For user-defined links, this value will be described in the definition of the user-defined link type.
loc_id specifies the location identifier of the group specified by group_name.
group_name specifies the group in which the link exists. If loc_id already specifies the group in which the link exists, group_name must be a dot (.).
The size in bytes of link_val is specified in size. The size value can be determined through a call to H5Lget_info_by_idx(); it is returned in the val_size field of the H5L_info_t struct. If size is smaller than the size of the returned value, then the string stored in link_val will be truncated to size bytes. For soft links, this means that the value will not be null terminated.
If the type of the link is unknown or uncertain, H5Lget_val_by_idx() should be called only after the type has been determined via a call to H5Lget_info_by_idx().
| herr_t H5Lmove | ( | hid_t | src_loc, |
| const char * | src_name, | ||
| hid_t | dst_loc, | ||
| const char * | dst_name, | ||
| hid_t | lcpl_id, | ||
| hid_t | lapl_id | ||
| ) |
Moves a link within an HDF5 file.
| [in] | src_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | src_name | Original link name |
| [in] | dst_loc | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | dst_name | New link name |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | lapl_id | Link access property list identifier |
H5Lmove() moves a link within an HDF5 file. The original link, src_name, is removed from src_loc and the new link, dst_name, is inserted at dst_loc. This change is accomplished as an atomic operation.
src_loc and src_name identify the original link. src_loc is the original location identifier; src_name is the path to the link and is interpreted relative to src_loc.
dst_loc and dst_name identify the new link. dst_loc is either a file or group identifier; dst_name is the path to the link and is interpreted relative to dst_loc.
lcpl_id and lapl_id are the link creation and link access property lists, respectively, associated with the new link, dst_name.
Through these property lists, several properties are available to govern the behavior of H5Lmove(). The property controlling creation of missing intermediate groups is set in the link creation property list with H5Pset_create_intermediate_group(); H5Lmove() ignores any other properties in the link creation property list. Properties controlling character encoding, link traversals, and external link prefixes are set in the link access property list with H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(), respectively.
| herr_t H5Lunpack_elink_val | ( | const void * | ext_linkval, |
| size_t | link_size, | ||
| unsigned * | flags, | ||
| const char ** | filename, | ||
| const char ** | obj_path | ||
| ) |
Decodes external link information.
| [in] | ext_linkval | Buffer containing external link information |
| [in] | link_size | Size, in bytes, of the ext_linkval buffer |
| [out] | flags | External link flags, packed as a bitmap (Reserved as a bitmap for flags; no flags are currently defined, so the only valid value * is 0.) |
| [out] | filename | Returned filename |
| [out] | obj_path | Returned object path, relative to filename |
H5Lunpack_elink_val() decodes the external link information returned by H5Lget_val() in the ext_linkval buffer.
ext_linkval should be the buffer set by H5Lget_val() and will consist of two NULL-terminated strings, the filename and object path, one after the other.
Given this buffer, H5Lunpack_elink_val() creates pointers to the filename and object path within the buffer and returns them in filename and obj_path, unless they are passed in as NULL.
H5Lunpack_elink_val() requires that ext_linkval contain a concatenated pair of null-terminated strings, so use of this function on a string that is not an external link udata buffer may result in a segmentation fault. This failure can be avoided by adhering to the following procedure:
1.9.7