|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
The C Interfaces:
H5Lcopy(
hid_t src_loc_id,
const char *src_name,
hid_t dest_loc_id,
const char *dest_name,
hid_t lcpl_id
hid_t lapl_id
)
H5Lcopy copies the link
specified by src_name
from the file or group specified by src_loc_id
to the destination location dest_loc_id.
The new copy of the link is created with the name dest_name.
The destination location, as specified in dest_loc_id,
may be a group in the current file.
If dest_loc_id is the file identifier, the copy is
placed in the 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 that specified in lcpl_id rather than 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.
H5Lcopy does not affect the object that the link points to.
hid_t src_loc_id
|
IN: Location identifier of the source link |
const char *src_name
|
IN: Name of the link to be copied |
hid_t dest_loc_id
|
IN: Location identifier specifying the destination of the copy |
const char *dest_name
|
IN: Name to be assigned to the new copy |
hid_t lcpl_id
|
IN: Link creation property list identifier |
hid_t lapl_id
|
IN: Link access property list identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_external(
const char *file_name,
const char *object_name,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_external creates a new soft link to an
external object, which is an object in a different HDF5 file
from the location of the link.
file_name identifies the file containing the
target object;
object_name specifies the path to the target object
within that file.
object_name must start at the target file’s
the root group but is not interpreted until lookup time.
link_loc_id and link_name specify the
location and name, respectively, of the new external link.
link_name is interpreted relative to
link_loc_id
lcpl_id and lapl_id are the
link creation and access property lists associated with the
new link.
An external link behaves similarly to a soft link, and like a soft link in an HDF5 file, it may dangle: the target object need not exist at the time that the link is created. Both are also known as symbolic links as they use a name to point to an object; hard links employ an object’s address in the file.
const char * file_name |
IN: Name of the file containing the target object. Neither the file nor the target object is required to exist. May be the file the link is being created in. |
const char *object_name |
IN: Path within the target file to the target object. |
hid_t link_loc_id |
IN: The file or group identifier for the new link. |
const char * link_name |
IN: The name of the new link. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_hard(
hid_t obj_loc_id,
const char *obj_name,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_hard creates a new hard link to a
pre-existing object in an HDF5 file.
The new link may be one of many that point to that object.
obj_loc_id and obj_name specify the
location and name, respectively, of the target object,
i.e., the object that the new hard link points to.
link_loc_id and link_name specify the
location and name, respectively, of the new hard link.
obj_name and link_name are interpreted
relative to obj_loc_id and link_loc_id,
respectively.
The target object must already exist in the file.
lcpl_id and lapl_id are the
link creation and access property lists associated with the
new link.
Hard and soft links are for use only if the target object
is in the current file.
If the desired target object is in a different file from the
new link, an external link may be created with
H5Lcreate_external.
The HDF5 library keeps a count of all hard links pointing to an
object; if the hard link count reaches zero (0),
the object will be deleted from the file. Creating new hard links
to an object will prevent it from being deleted if other links
are removed.
The library maintains no similar count for soft links and they
can dangle.
hid_t obj_loc_id |
IN: The file or group identifier for the target object. |
const char *obj_name |
IN: Name of the target object, which must already exist. |
hid_t link_loc_id |
IN: The file or group identifier for the new link. |
const char * link_name |
IN: The name of the new link. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_soft(
const char *target_path,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_soft creates a new soft link
to an object in an HDF5 file.
The new link may be one of many that point to that object.
target_path specifies the path to the target object,
i.e., the object that the new soft link points to.
target_path can be anything and is interpreted 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 relative to
link_loc_id
For example, the following statement specifies that
the target path is ./foo,
the location of the new link is ./x/y/bar, and
the name of the new link is new_link:
status = H5Lcreate_soft(./foo, ./x/y/bar/, new_link,
H5P_DEFAULT, H5P_DEFAULT)
A subsequent request for ./x/y/bar/new_link
would look up the object ./x/y/bar/foo.
target_path specifies the path to the target object,
i.e., the object that the new soft link points to.
target_path can be anything and is interpreted at
lookup time. This path may be absolute in the file or relative
to link_loc_id.
For instance, if target_path is ./foo,
link_loc_id specifies ./x/y/bar,
and a request is made for ./x/y/bar/link_name,
then the actual object looked up is ./x/y/bar/foo.
H5Lcreate_soft is for use only if the target object
is in the current file.
If the desired target object is in a different file from the
new link, use
H5Lcreate_external
to create an external link.
lcpl_id and lapl_id are the
link creation and access property lists associated with the
new link.
Soft links and external links are also known as symbolic links as they use a name to point to an object; hard links employ an object’s address in the file.
Unlike hard links, a soft link in an HDF5 file is allowed to dangle, meaning that the target object need not exist at the time that the link is created.
The HDF5 library does not keep a count of soft links as it does of hard links.
const char *target_path |
IN: Path to the target object, which is not required to exist. |
hid_t link_loc_id |
IN: The file or group identifier for the new link. |
const char * link_name |
IN: The name of the new link. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_ud(
hid_t link_loc_id,
const char *link_name,
H5L_type_t link_type,
const char *udata,
size_t udata_size,
hid_t lcpl_id,
hid_t lapl_id
)
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.
The link class of the new link, link_type,
must already be registered with the library.
Such user-defined link classes are registered with
H5Lregister.
The H5L_type_t, the ENUM specifying
valid link classes, is defined in H5Lpublic.h.
Valid values without registered user-defined link types
include the following:
H5L_LINK_HARD
H5L_LINK_SOFT
H5L_LINK_EXTERNAL
Registering a user-defined link type with H5Lregister
adds a user-defined symbol to the H5L_type_t
ENUM;
that user-defined symbol is then passed in the link_type
parameter of H5Lcreate_ud
and will be returned by H5Lget_info.
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.
hid_t link_loc_id
|
IN: Link location identifier |
const char *link_name
|
IN: Link name |
H5L_type_t link_type
|
IN: User-defined link class |
const char *udata
|
IN: User-supplied link information |
size_t udata_size
|
IN: Size of udata buffer
|
hid_t lcpl_id
|
IN: Link creation property list identifier |
hid_t lapl_id
|
IN: Link access property list identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lexists(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
H5Lexists allows an application to determine if a link
with a particular name exists in a group. The link could be of any
type, just the presence of a link with that name is checked.
hid_t loc_id
|
IN: Identifier of the file or group to query. |
const char *name
|
IN: The name of the link to check. |
hid_t lapl_id
|
IN: Link access property list identifier. |
TRUE or FALSE if successful;
otherwise returns a negative value.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_info(
hid_t link_loc_id,
const char *link_name,
H5L_info_t *link_buff,
hid_t lapl_id
)
H5Lget_info returns information about the
specified link through the link_buff argument.
A file or group identifier, link_loc_id, specifies the
location of the link.
A link name, link_name, interpreted relative to
loc_id, specifies the link being queried.
lapl_id is the link access property list associated
with the link 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_info returns information about
link_name in the data structure
H5L_info_t,
which is described below and defined in H5Lpublic.h.
This structure is returned in the buffer link_buff.
typedef struct H5L_info_t {
H5T_cset_t cset;
int64_t create_order;
hbool_t create_order_valid;
H5L_type_t link_type;
union {
haddr_t address;
size_t link_len;
} u;
} H5Linfo_t
In the above struct,
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 |
create_order specifies the link’s creation order
position while create_order_valid indicates whether
the value in create_order is valid.
create_order 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 create_order for the
last link created will be larger than the number of links remaining
in the group.
If create_order is TRUE,
the value in create_order is known to be valid;
if create_order is FALSE,
the value in create_order is presumed to be invalid;
link_type specifies the link class.
Valid values include the following:
H5L_LINK_HARD
| Hard link | |
H5L_LINK_SOFT
| Soft link | |
H5L_LINK_EXTERNAL
| External link | |
H5L_LINK_ERROR
| Error |
address and link_len 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, link_len will be
the length of the link value, e.g., the length of the name of
the pointed-to object with a null terminator.
hid_t link_loc_id |
IN: File or group identifier. |
const char *link_name |
IN: Name of the link for which information is being sought. |
H5L_info_t *link_buff |
OUT: Buffer in which link information is returned. |
hid_t lapl_id |
IN: Link access property list identifier. |
link_buff (if non-null) initialized.
Otherwise returns a negative value.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_info_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
H5L_info_t *link_val,
hid_t lapl_id
)
H5Lget_info_by_idx 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
index_field, order, and n
as follows:
index_field 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
index_field, order, and n are
H5_INDEX_NAME, H5_ITER_DEC, and 5,
respectively.
H5_INDEX_NAME indicates that the links are accessed
in alpha-numeric 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 H5Literate
for a list of valid values and further discussion regarding
index_field and order.
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
H5L_info_t *link_val |
OUT: Buffer in which link value is returned |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_name_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
char *name,
size_t size,
hid_t lapl_id
)
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, index_field.
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
The size in bytes of name is specified in
size.
If size is unknown, it can be determined via an
initial H5Lget_name_by_idx call with name
set to NULL; the function's return value will be the
size of the name.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
char *name |
OUT: Buffer in which link value is returned |
size_t size |
IN: Size in bytes of name |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_val(
hid_t link_loc_id,
const char *link_name,
void *linkval_buff,
size_t size,
hid_t lapl_id
)
H5Lget_val returns the link value of the link
link_name.
The parameter link_loc_id is a file or group identifier.
link_name identifies a symbolic link and is defined
relative to link_loc_id.
Symbolic links include soft and external links and some user-defined
links.
The link value is returned in the buffer linkval_buff.
For soft 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 linkval_buff
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
link_len field of the H5L_info_t struct.
If size is smaller than the size of the returned
value, then the string stored in linkval_buff
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 linkval_buff 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 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
link_name is a symbolic link.
This can be deteremined from the link_type field
of the H5L_info_t struct.
hid_t link_loc_id |
IN: File or group identifier. |
const char *link_name |
IN: Link whose value is to be returned. |
void *linkval_buff |
OUT: The buffer to hold the returned link value. |
size_t size |
IN: Maximum number of characters of link value to be returned. |
hid_t lapl_id |
IN: List access property list identifier. |
linkval_buff, if successful.
Otherwise returns a negative value.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_val_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
char *value_buf,
size_t size,
hid_t lapl_id
)
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.
H5Lunpack_elink_val
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
The size in bytes of name is specified in size.
If size is unknown, it can be determined via an
initial H5Lget_val_by_idx call with size
set to NULL; size will be returned with
the actual size of name.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
H5L_info_t *link_val |
OUT: Buffer in which link value is returned |
size_t size |
IN: Size in bytes of name |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lis_registered(
H5L_type_t link_cls_id
)
H5Lis_registered tests whether a user-defined link
class is currently registered, either by the HDF5 Library
or by the user through the use of
H5Lregister.
A link class must be registered to create new links of that type or to traverse exisitng links of that type.
H5L_type_t link_cls_id
|
IN: User-defined link class identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Literate(
hid_t group_id,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t *idx,
H5L_iterate_t op,
void *op_data
)
H5Literate iterates through the links
in a group, specified by group_id,
in the order of the specified index, index_type,
using a user-defined callback routine op.
H5Literate does not recursively follow links into
subgroups of the specified group.
Three parameters are used to manage progress of the iteration:
index_type, order, and idx.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
idx allows an interrupted iteration to be resumed;
it is passed in by the application with a starting point and
returned by the library with the point at which the iteration stopped.
As mentioned above, H5Literate is not recursive.
In particular, if a member of group_id is found to be
a group, call it subgroup_a, H5Literate
does not examine the members of subgroup_a.
When recursive iteration is required, the application can
do either of the following:
H5Literate:
H5Lvisit
H5Lvisit_by_name
H5Ovisit
H5Ovisit_by_name
H5Literate on discovered subgroups.
H5Literate is the same as H5Giterate,
except that H5Giterate always proceeds in alphanumeric
order.
hid_t group_id |
IN: Identifier specifying subject group |
H5_index_t index_type |
IN: Type of index which determines the order |
H5_iter_order_t order |
IN: Order within index |
hsize_t *idx |
IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted |
H5L_iterate_t op |
IN: Callback function passing data regarding the link to the calling application |
void *op_data |
IN: User-defined pointer to data required by the application for its processing of the link |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Literate_by_name(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t *idx,
H5L_iterate_t op,
void *op_data,
hid_t *lapl_id
)
H5Literate_by_name iterates through the links
in a group, specified by loc_id and group_name,
in the order of the specified index, index_type,
using a user-defined callback routine op.
H5Literate_by_name does not recursively follow links into
subgroups of the specified group.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
idx allows an interrupted iteration to be resumed;
it is passed in by the application with a starting point and
returned by the library with the point at which the iteration stopped.
H5Literate_by_name is not recursive.
In particular, if a member of group_name is found to be
a group, call it subgroup_a, H5Literate_by_name
does not examine the members of subgroup_a.
When recursive iteration is required, the application must handle
the recursion, explicitly calling H5Literate_by_name
on discovered subgroups.
H5Literate_by_name is the same as H5Giterate,
except that H5Giterate always proceeds in alphanumeric
order.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_type |
IN: Type of index which determines the order |
H5_iter_order_t order |
IN: Order within index |
hsize_t *idx |
IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted |
H5L_iterate_t op |
IN: Callback function passing data regarding the link to the calling application |
void *op_data |
IN: User-defined pointer to data required by the application for its processing of the link |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lmove(
hid_t src_loc_id,
const char *src_name,
hid_t dest_loc_id,
const char *dest_name,
hid_t lcpl,
hid_t lapl
)
H5Lmove renames a link within an HDF5 file.
The original link, src_name, is removed from the
group graph and the new link, dest_name,
is inserted; this change is accomplished as an atomic operation.
src_loc_id and src_name identify the
existing link.
src_loc_id is either a file or group identifier;
src_name is the path to the link and is interpreted
relative to src_loc_id.
dest_loc_id and dest_name identify the
new link.
dest_loc_id is either a file or group identifier;
dest_name is the path to the link and is interpreted
relative to dest_loc_id.
lcpl and lapl are the link creation
and link access property lists, respectively, associated with
the new link, dest_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.
H5Lmove.
If the link being moved is on the only path leading to an HDF5 object,
that object may become permanently inaccessible in the file.
hid_t src_loc_id |
IN: Original file or group identifier. |
const char *src_name |
IN: Original link name. |
hid_t dest_loc_id |
IN: Destination file or group identifier. |
const char *dest_name |
IN: New link name. |
hid_t lcpl_id |
IN: Link creation property list identifier to be associated with the new link. |
hid_t lapl_id |
IN: Link access property list identifier to be associated with the new link. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lregister(
const H5L_class_t * link_class
)
H5Lregister registers a class of user-defined links,
or changes the behavior of an existing class.
The struct H5L_class_t is defined in
H5Lpublic.h as follows:
typedef struct H5L_class_t {
int version; /* Version number of this struct */
H5L_type_t class_id; /* Link class identifier */
const char *comment; /* Comment for debugging */
H5L_create_func_t create_func; /* Callback during link creation */
H5L_move_func_t move_func; /* Callback after moving link */
H5L_copy_func_t copy_func; /* Callback after copying link */
H5L_traverse_func_t trav_func; /* The main traversal function */
H5L_delete_func_t del_func; /* Callback for link deletion */
H5L_query_func_t query_func; /* Callback for queries */
} H5L_class_t;
The link class passed in will override any existing link
class for the specified link class identifier class_id.
The class definition must include at least a
H5L_class_t version
(which should be H5L_LINK_CLASS_T_VERS),
a link class identifier, and a traversal function,
trav_func.
Valid values of class_id include the following
(defined in H5Lpublic.h:
H5L_TYPE_HARD
| Hard link | |
H5L_TYPE_SOFT
| Soft link | |
H5L_TYPE_EXTERNAL
| External link |
class_id must be a value between
H5L_LINK_UD_MIN and H5L_LINK_UD_MAX,
Note that as distributed with the HDF5 Library,
the external link class is implemented as an example user-defined link
class and H5L_LINK_EXTERNAL equals
H5L_LINK_UD_MIN. Therefore, class_id
should not equal H5L_LINK_UD_MIN unless you intend to
overwrite or modify the behavior of external links.
To summarize:
H5L_TYPE_ERROR indicates that an error has occurred.
|
H5L_TYPE_MAX is the maximum allowed value for a
link type identifier.
|
H5L_TYPE_UD_MIN equals H5L_TYPE_EXTERNAL.
|
H5L_TYPE_UD_MAX equals H5L_TYPE_MAX.
|
H5L_TYPE_HARD and H5L_TYPE_SOFT
reside in the reserved space below H5L_TYPE_UD_MIN.
|
class_id values.
const H5L_class_t * link_class
|
IN: Struct describing user-defined link class |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ldelete(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
H5Ldelete removes the link specified by
name from the location loc_id.
If the link being removed is a hard ink, 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.
Note that space identified as freespace is available for re-use only as long as the file remains open; once a file has been closed, the HDF5 library loses track of freespace. See “Freespace Management” in “Performace Analysis and Issues” for further details.
H5Ldelete;
if the link being removed is on the only path leading to an
HDF5 object, that object may become permanently inaccessible in
the file.
hid_t loc_id |
IN: Identifier of the file or group containing the object. |
const char *name |
IN: Name of the link to delete. |
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ldelete_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
hid_t lapl_id
)
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 (.).
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lunpack_elink_val(
char *ext_linkval,
size_t link_size,
const char **filename,
const char **obj_path
)
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 strings that are not external link
udata buffers may result in a segmentation fault.
This failure can be avoided by adhering to the following procedure:
H5Lget_info to get the link type
and the size of the link value.
H5L_LINK_EXTERNAL.
H5Lget_val to get the link value.
H5Lunpack_elink_val to unpack that value.
|
const char *ext_linkval
|
IN: Buffer containing external link information |
size_t link_size
|
IN: Size, in bytes, of the ext_linkval
buffer
|
const char **filename
|
OUT: Returned filename |
const char **obj_path
|
OUT: Returned object path, relative to
filename
|
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lunregister(
H5L_type_t link_cls_id
)
H5Lunregister unregisters a class of user-defined links,
preventing them from being traversed, queried, moved, etc.
A link class can be re-registered using H5Lregister.
H5L_type_t link_cls_id
|
IN: User-defined link class identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lvisit(
hid_t group_id,
H5_index_t index_type,
H5_iter_order_t order,
H5L_iterate_t op,
void *op_data
)
H5Lvisit is a recursive iteration function
to visit all links in and below a group in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those links
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
The group serving as the root of the iteration is specified by
it’s group identifier, group_id
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Lpublic.h):
(*H5L_iterate_t)(
hid_t g_id,
const char *name,
const H5L_info_t *info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
g_id
|
Group that serves as root of the iteration; same value
as the H5Lvisit group_id parameter
|
|
name
|
Name of link, relative to g_id,
being examined at current step of the iteration
|
|
info
| H5L_info_t struct containing information regarding that link |
|
op_data
|
User-defined pointer to data required by the application
in processing the link;
a pass-through of the op_data pointer provided
with the H5Lvisit function call
|
The H5L_info_t struct is defined (in H5Lpublic.h)
as follows:
typedef struct {
H5L_type_t type; /* Type of link */
hbool_t corder_valid; /* Indicates whether creation */
/* order is valid */
int64_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of link name */
union {
haddr_t address; /* Address hard link points to */
size_t val_size; /* Size of soft link or */
/* user-defined link value */
} u;
} H5L_info_t;
The H5Lvisit op_data parameter is a
user-defined pointer to the data required to process links
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
H5Lvisit and
H5Ovisit
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
hid_t group_id
|
IN: Identifier of the group at which the recursive iteration begins. |
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5L_iterate_t op
|
IN: Callback function passing data regarding the link to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the link |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lvisit_by_name(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
H5L_iterate_t op,
void *op_data,
hid_t lapl_id
)
H5Lvisit_by_name is a recursive iteration function
to visit all links in and below a group in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those links
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
The group serving as the root of the iteration is specified by
the loc_id / group_name parameter pair.
loc_id specifies a file or group;
group_name specifies either
a group in the file (with an absolute name based in the
file’s root group) or
a group relative to loc_id.
If loc_id fully specifies the group that is to
serve as the root of the iteration, group_name should
be '.' (a dot).
(Note that when loc_id fully specifies the the
group that is to serve as the root of the iteration,
the user may wish to consider using
H5Lvisit
instead of H5Lvisit_by_name.)
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Lpublic.h):
(*H5L_iterate_t)(
hid_t g_id,
const char *name,
const H5L_info_t *info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
g_id
|
Group that serves as root of the iteration,
i.e., identifier of the group specified by the
H5Lvisit_by_name loc_id /
group_name parameter pair
|
|
name
|
Name of link, relative to g_id,
being examined at current step of the iteration
|
|
info
| H5L_info_t struct containing information regarding that link |
|
op_data
|
User-defined pointer to data required by the application
in processing the link;
a pass-through of the op_data pointer provided
with the H5Lvisit_by_name function call
|
The H5L_info_t struct is defined (in H5Lpublic.h)
as follows:
typedef struct {
H5L_type_t type; /* Type of link */
hbool_t corder_valid; /* Indicates whether creation */
/* order is valid */
int64_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of link name */
union {
haddr_t address; /* Address hard link points to */
size_t val_size; /* Size of soft link or */
/* user-defined link value */
} u;
} H5L_info_t;
The H5Lvisit_by_name op_data parameter is a
user-defined pointer to the data required to process links
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
lapl_id is a link access property list.
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).
H5Lvisit_by_name and
H5Ovisit_by_name
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
hid_t loc_id
|
IN: Identifier of a file or group |
const char *name
|
IN: Name of the group,
generally relative to loc_id,
that will serve as root of the iteration
|
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5L_iterate_t op
|
IN: Callback function passing data regarding the link to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the link |
hid_t lapl_id
|
IN: Link access property list identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
