Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
Functions
Advanced Link Functions
Links (H5L)

Detailed Description

Registration of User-defined links

Functions

herr_t H5Lregister (const H5L_class_t *cls)
 Registers a user-defined link class or changes behavior of an existing class.
 
herr_t H5Lunregister (H5L_type_t id)
 Unregisters a class of user-defined links.
 
htri_t H5Lis_registered (H5L_type_t id)
 Determines whether a class of user-defined links is registered.
 

Function Documentation

◆ H5Lis_registered()

htri_t H5Lis_registered ( H5L_type_t  id)

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

Parameters
[in]idUser-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]clsPointer 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;
H5L_create_func_t
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.
Definition H5Ldevelop.h:55
H5L_query_func_t
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.
Definition H5Ldevelop.h:82
H5L_delete_func_t
herr_t(* H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, size_t lnkdata_size)
Callback for link deletion.
Definition H5Ldevelop.h:75
H5L_copy_func_t
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.
Definition H5Ldevelop.h:65
H5L_traverse_func_t
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.
Definition H5Ldevelop.h:70
H5L_move_func_t
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.
Definition H5Ldevelop.h:60
H5L_type_t
H5L_type_t
Link class types.
Definition H5Lpublic.h:63
H5L_class_t
Link prototype.
Definition H5Ldevelop.h:93

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

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_HARDHard link
H5L_TYPE_SOFTSoft link
H5L_TYPE_EXTERNALExternal link
H5L_TYPE_ERRORError

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]idUser-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