#include "H5public.h"
#include "H5Ipublic.h"
#include "H5Opublic.h"
#include "H5Tpublic.h"

Data Structures
struct	H5L_info2_t
	Information struct for links. More...

struct	H5L_class_t
	Link prototype. More...

struct	H5L_info1_t

struct	H5L_class_0_t

Macros
#define	H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */
	Maximum length of a link's name. More...

#define	H5L_SAME_LOC (hid_t)0
	Macro to indicate operation occurs on same location. More...

#define	H5L_LINK_CLASS_T_VERS 1
	Current version of the H5L_class_t struct. More...

#define	H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT
	Maximum value link value for "built-in" link types. More...

#define	H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL
	Link ids at or above this value are "user-defined" link types. More...

#define	H5L_TYPE_UD_MAX H5L_TYPE_MAX
	Maximum link id value for "user-defined" link types. More...

#define	H5L_LINK_CLASS_T_VERS_0 0

Typedefs
typedef herr_t(*	H5L_create_func_t) (const char link_name, hid_t loc_group, const void lnkdata, size_t lnkdata_size, hid_t lcpl_id)
	Link creation callback. More...

typedef herr_t(*	H5L_move_func_t) (const char new_name, hid_t new_loc, const void lnkdata, size_t lnkdata_size)
	Callback for link move. More...

typedef herr_t(*	H5L_copy_func_t) (const char new_name, hid_t new_loc, const void lnkdata, size_t lnkdata_size)
	Callback for link copy. More...

typedef hid_t(*	H5L_traverse_func_t) (const char link_name, hid_t cur_group, const void lnkdata, size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id)
	Callback during link traversal. More...

typedef herr_t(*	H5L_delete_func_t) (const char link_name, hid_t file, const void lnkdata, size_t lnkdata_size)
	Callback for link deletion. More...

typedef ssize_t(*	H5L_query_func_t) (const char link_name, const void lnkdata, size_t lnkdata_size, void *buf, size_t buf_size)
	Callback for querying the link. More...

typedef herr_t(*	H5L_iterate2_t) (hid_t group, const char name, const H5L_info2_t info, void *op_data)
	Prototype for H5Literate2(), H5Literate_by_name2() operator. More...

typedef herr_t(*	H5L_elink_traverse_t) (const char parent_file_name, const char parent_group_name, const char child_file_name, const char child_object_name, unsigned acc_flags, hid_t fapl_id, void op_data)
	Callback for external link traversal. More...

typedef hid_t(*	H5L_traverse_0_func_t) (const char link_name, hid_t cur_group, const void lnkdata, size_t lnkdata_size, hid_t lapl_id)

typedef herr_t(*	H5L_iterate1_t) (hid_t group, const char name, const H5L_info1_t info, void *op_data)

Enumerations
enum	H5L_type_t { H5L_TYPE_ERROR = (-1), H5L_TYPE_HARD = 0, H5L_TYPE_SOFT = 1, H5L_TYPE_EXTERNAL = 64, H5L_TYPE_MAX = 255 }
	Link class types. More...

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. More...

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. More...

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. More...

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. More...

herr_t	H5Ldelete (hid_t loc_id, const char *name, hid_t lapl_id)
	Removes a link from a group. More...

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. More...

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. More...

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. More...

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. More...

herr_t	H5Lget_info2 (hid_t loc_id, const char name, H5L_info2_t linfo, hid_t lapl_id)
	Returns information about a link. More...

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. More...

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. More...

herr_t	H5Literate2 (hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t idx, H5L_iterate2_t op, void op_data)
	Iterates over links in a group, with user callback routine, according to the order within an index. More...

herr_t	H5Literate_by_name2 (hid_t loc_id, const char group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t idx, H5L_iterate2_t op, void *op_data, hid_t lapl_id)
	Iterates through links in a group. More...

herr_t	H5Lvisit2 (hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data)
	Recursively visits all links starting from a specified group. More...

herr_t	H5Lvisit_by_name2 (hid_t loc_id, const char group_name, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void op_data, hid_t lapl_id)
	Recursively visits all links starting from a specified group. More...

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. More...

herr_t	H5Lregister (const H5L_class_t *cls)
	Registers a user-defined link class or changes behavior of an existing class. More...

herr_t	H5Lunregister (H5L_type_t id)
	Unregisters a class of user-defined links. More...

htri_t	H5Lis_registered (H5L_type_t id)
	Determines whether a class of user-defined links is registered. More...

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. More...

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. More...

herr_t	H5Lget_info1 (hid_t loc_id, const char name, H5L_info1_t linfo, hid_t lapl_id)
	Returns information about a link. More...

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. More...

herr_t	H5Literate1 (hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t idx, H5L_iterate1_t op, void op_data)
	Iterates over links in a group, with user callback routine, according to the order within an index. More...

herr_t	H5Literate_by_name1 (hid_t loc_id, const char group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t idx, H5L_iterate1_t op, void *op_data, hid_t lapl_id)
	Iterates through links in a group by its name. More...

herr_t	H5Lvisit1 (hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data)
	Recursively visits all links starting from a specified group. More...

herr_t	H5Lvisit_by_name1 (hid_t loc_id, const char group_name, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void op_data, hid_t lapl_id)
	Recursively visits all links starting from a specified group. More...

Macro Definition Documentation

◆ H5L_LINK_CLASS_T_VERS

#define H5L_LINK_CLASS_T_VERS 1

Current version of the H5L_class_t struct.

◆ H5L_LINK_CLASS_T_VERS_0

#define H5L_LINK_CLASS_T_VERS_0 0

◆ H5L_MAX_LINK_NAME_LEN

#define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */

Maximum length of a link's name.

The maximum length of a link's name is encoded in a 32-bit unsigned integer.

◆ H5L_SAME_LOC

#define H5L_SAME_LOC (hid_t)0

Macro to indicate operation occurs on same location.

◆ H5L_TYPE_BUILTIN_MAX

#define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT

Maximum value link value for "built-in" link types.

◆ H5L_TYPE_UD_MAX

#define H5L_TYPE_UD_MAX H5L_TYPE_MAX

Maximum link id value for "user-defined" link types.

◆ H5L_TYPE_UD_MIN

#define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL

Link ids at or above this value are "user-defined" link types.

Typedef Documentation

◆ H5L_copy_func_t

typedef herr_t(* H5L_copy_func_t) (const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size)

Callback for link copy.

◆ H5L_create_func_t

typedef herr_t(* H5L_create_func_t) (const char *link_name, hid_t loc_group, const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id)

Link creation callback.

◆ H5L_delete_func_t

typedef herr_t(* H5L_delete_func_t) (const char *link_name, hid_t file, const void *lnkdata, size_t lnkdata_size)

Callback for link deletion.

◆ H5L_elink_traverse_t

typedef herr_t(* H5L_elink_traverse_t) (const char *parent_file_name, const char *parent_group_name, const char *child_file_name, const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data)

Callback for external link traversal.

◆ H5L_iterate1_t

typedef herr_t(* H5L_iterate1_t) (hid_t group, const char *name, const H5L_info1_t *info, void *op_data)

Prototype for H5Literate1() / H5Literate_by_name1() operator

◆ H5L_iterate2_t

typedef herr_t(* H5L_iterate2_t) (hid_t group, const char *name, const H5L_info2_t *info, void *op_data)

Prototype for H5Literate2(), H5Literate_by_name2() operator.

The H5O_token_t version is used in the VOL layer and future public API calls.

◆ H5L_move_func_t

typedef herr_t(* H5L_move_func_t) (const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size)

Callback for link move.

◆ H5L_query_func_t

typedef ssize_t(* H5L_query_func_t) (const char *link_name, const void *lnkdata, size_t lnkdata_size, void *buf, size_t buf_size)

Callback for querying the link.

Returns the size of the buffer needed.

◆ H5L_traverse_0_func_t

typedef hid_t(* H5L_traverse_0_func_t) (const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id)

Callback during link traversal

◆ H5L_traverse_func_t

typedef hid_t(* H5L_traverse_func_t) (const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id)

Callback during link traversal.

Enumeration Type Documentation

◆ H5L_type_t

enum H5L_type_t

Link class types.

Values less than 64 are reserved for the HDF5 library's internal use. Values 64 to 255 are for "user-defined" link class types; these types are defined by HDF5 but their behavior can be overridden by users. Users who want to create new classes of links should contact the HDF5 development team at help@.nosp@m.hdfg.nosp@m.roup..nosp@m.org. These values can never change because they appear in HDF5 files.

Enumerator
H5L_TYPE_ERROR	Invalid link type id
H5L_TYPE_HARD	Hard link id
H5L_TYPE_SOFT	Soft link id
H5L_TYPE_EXTERNAL	External link id
H5L_TYPE_MAX	Maximum link type id

Function Documentation

◆ H5Lis_registered()

htri_t H5Lis_registered ( H5L_type_t id )

Determines whether a class of user-defined links is registered.

Parameters

[in] id User-defined link class identifier

Returns: Returns zero (false), a positive (true) or a negative (failure) value.

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().

Note: A link class must be registered to create new links of that type or to traverse existing links of that type.

Since: 1.8.0

◆ H5Lregister()

herr_t H5Lregister ( const H5L_class_t * cls )

Registers a user-defined link class or changes behavior of an existing class.

Parameters

[in] cls Pointer to a buffer containing the struct describing the user-defined link class

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Lregister() registers a class of user-defined links, or changes the behavior of an existing class.

cls is a pointer to a buffer containing a copy of the H5L_class_t struct. This struct is defined in H5Lpublic.h as follows:

typedef struct {
    int                 version;     
    H5L_type_t          id;          
    const char *        comment;     
    H5L_create_func_t   create_func; 
    H5L_move_func_t     move_func;   
    H5L_copy_func_t     copy_func;   
    H5L_traverse_func_t trav_func;   
    H5L_delete_func_t   del_func;    
    H5L_query_func_t    query_func;  
} H5L_class_t;

The class definition passed with cls must include at least the following:

An H5L_class_t version (which should be H5L_LINK_CLASS_T_VERS)
A link class identifier, class_id
A traversal function, trav_func

Remaining struct members are optional and may be passed as NULL.

The link class passed in class_id must be in the user-definable range between H5L_TYPE_UD_MIN and H5L_TYPE_UD_MAX (see the table below) and will override any existing link class with that identifier.

As distributed, valid values of class_id used in HDF5 include the following (defined in H5Lpublic.h):

H5L_TYPE_HARD	Hard link
H5L_TYPE_SOFT	Soft link
H5L_TYPE_EXTERNAL	External link
H5L_TYPE_ERROR	Error

The hard and soft link class identifiers cannot be modified or reassigned, but the external link class is implemented as an example in the user-definable link class identifier range. H5Lregister() is used to register additional link classes. It could also be used to modify the behavior of the external link class, though that is not recommended.

The following table summarizes existing link types and values and the reserved and user-definable link class identifier value ranges.

Link class identifier or Value range	Description	Link class or label
0 to 63	Reserved range
64 to 255	User-definable range
64	Minimum user-defined value	H5L_TYPE_UD_MIN
64	External link	H5L_TYPE_EXTERNAL
255	Maximum user-defined value	H5L_TYPE_UD_MAX
255	Maximum value	H5L_TYPE_MAX
-1	Error	H5L_TYPE_ERROR

Note that HDF5 internally registers user-defined link classes only by the numeric value of the link class identifier. An application, on the other hand, will generally use a name for a user-defined class, if for no other purpose than as a variable name. Assume, for example, that a complex link type is registered with the link class identifier 73 and that the code includes the following assignment:

H5L_TYPE_COMPLEX_A = 73

The application can refer to the link class with a term, H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing the code, while HDF5 recognizes it by the more cryptic numeric identifier, 73.

Attention

Important details and considerations include the following:

If you plan to distribute files or software with a user-defined link class, please contact the Help Desk at The HDF Group to help prevent collisions between class_id values. See below.
As distributed with HDF5, the external link class is implemented as an example of a user-defined link class with H5L_TYPE_EXTERNAL equal to H5L_TYPE_UD_MIN. class_id in the H5L_class_t struct must not equal H5L_TYPE_UD_MIN unless you intend to overwrite or modify the behavior of external links.
H5Lregister() can be used only with link class identifiers in the user-definable range (see table above).
The hard and soft links defined by the HDF5 library, H5L_TYPE_HARD and H5L_TYPE_SOFT, reside in the reserved range below H5L_TYPE_UD_MIN and cannot be redefined or modified.
H5Lis_registered() can be used to determine whether a desired link class identifier is available. Note that this function will tell you only whether the link class identifier has been registered with the installed copy of HDF5; it cannot tell you whether the link class has been registered with The HDF Group.
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_ERROR indicates that an error has occurred.

Note

Registration with The HDF Group:
There are sometimes reasons to take a broader approach to registering a user-defined link class than just invoking H5Lregister(). For example:

A user-defined link class is intended for use across an organization, among collaborators, or across a community of users.
An application or library overlying HDF5 invokes a user-defined link class that must be shipped with the software.
Files are distributed that make use of a user-defined link class.
Or simply, a specific user-defined link class is thought to be widely useful.

In such cases, you are encouraged to register that link class with The HDF Group's Helpdesk. The HDF Group maintains a registry of known user-defined link classes and tracks the selected link class identifiers. This registry is intended to reduce the risk of collisions between class_id values and to help coordinate the use of specialized link classes.

Since: 1.8.0

◆ H5Lunregister()

herr_t H5Lunregister ( H5L_type_t id )

Unregisters a class of user-defined links.

Parameters

[in] id User-defined link class identifier

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Lunregister() unregisters a class of user-defined links, preventing them from being traversed, queried, moved, etc.

Note: A link class can be re-registered using H5Lregister().

Since: 1.8.0

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ H5L_LINK_CLASS_T_VERS

◆ H5L_LINK_CLASS_T_VERS_0

◆ H5L_MAX_LINK_NAME_LEN

◆ H5L_SAME_LOC

◆ H5L_TYPE_BUILTIN_MAX

◆ H5L_TYPE_UD_MAX

◆ H5L_TYPE_UD_MIN

Typedef Documentation

◆ H5L_copy_func_t

◆ H5L_create_func_t

◆ H5L_delete_func_t

◆ H5L_elink_traverse_t

◆ H5L_iterate1_t

◆ H5L_iterate2_t

◆ H5L_move_func_t

◆ H5L_query_func_t

◆ H5L_traverse_0_func_t

◆ H5L_traverse_func_t

Enumeration Type Documentation

◆ H5L_type_t

Function Documentation

◆ H5Lis_registered()

◆ H5Lregister()

◆ H5Lunregister()