Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0
API Reference
Dynamically-loaded Plugins (H5PL)

Detailed Description

Use the functions in this module to manage the loading behavior of HDF5 plugins.

CreateRead
{
__label__ fail_set;
// enable ONLY filter plugins
ret_val = EXIT_FAILURE;
goto fail_set;
}
// ensure that "/tmp" is at the front of the search path list
if (H5PLprepend("/tmp") < 0) {
ret_val = EXIT_FAILURE;
}
fail_set:;
}
#define H5PL_FILTER_PLUGIN
Definition: H5PLpublic.h:44
herr_t H5PLprepend(const char *search_path)
Inserts a plugin path at the beginning of the plugin search path list.
herr_t H5PLset_loading_state(unsigned int plugin_control_mask)
Controls the loadability of dynamic plugin types.
{
__label__ fail_read;
unsigned size, mask;
char buf[255];
// retrieve the number of entries in the plugin path list
if (H5PLsize(&size) < 0) {
ret_val = EXIT_FAILURE;
goto fail_read;
}
printf("Number of stored plugin paths: %d\n", size);
// check the plugin state mask
if (H5PLget_loading_state(&mask) < 0) {
ret_val = EXIT_FAILURE;
goto fail_read;
}
printf("Filter plugins %s be loaded.\n", (mask & H5PL_FILTER_PLUGIN) == 1 ? "can" : "can't");
printf("VOL plugins %s be loaded.\n", (mask & H5PL_VOL_PLUGIN) == 2 ? "can" : "can't");
// print the paths in the plugin path list
for (unsigned i = 0; i < size; ++i) {
if (H5PLget(i, buf, 255) < 0) {
ret_val = EXIT_FAILURE;
break;
}
printf("%s\n", buf);
}
fail_read:;
}
#define H5PL_VOL_PLUGIN
Definition: H5PLpublic.h:45
herr_t H5PLsize(unsigned int *num_paths)
Retrieves the number of stored plugin paths.
ssize_t H5PLget(unsigned int index, char *path_buf, size_t buf_size)
Queries the plugin search path list at the specified index.
herr_t H5PLget_loading_state(unsigned int *plugin_control_mask)
Queries the loadability of dynamic plugin types.
UpdateDelete
{
// replace "/tmp" with something more sensible
if (H5PLreplace("/foo/bar", 0) < 0) {
ret_val = EXIT_FAILURE;
}
}
herr_t H5PLreplace(const char *search_path, unsigned int index)
Replaces the path at the specified index in the plugin search path list.
{
__label__ fail_delete;
unsigned size;
if (H5PLsize(&size) < 0) {
ret_val = EXIT_FAILURE;
goto fail_delete;
}
// clean out the list of plugin paths
for (int i = size - 1; i >= 0; --i) {
if (H5PLremove(i) < 0) {
ret_val = EXIT_FAILURE;
break;
}
}
fail_delete:;
}
herr_t H5PLremove(unsigned int index)
Removes a plugin path at a specified index from the plugin search path list.
Attention
The loading behavior of HDF5 plugins can be controlled via the functions described below and certain environment variables, such as HDF5_PLUGIN_PRELOAD and HDF5_PLUGIN_PATH.

Functions

herr_t H5PLset_loading_state (unsigned int plugin_control_mask)
 Controls the loadability of dynamic plugin types. More...
 
herr_t H5PLget_loading_state (unsigned int *plugin_control_mask)
 Queries the loadability of dynamic plugin types. More...
 
herr_t H5PLappend (const char *search_path)
 Inserts a plugin path at the end of the plugin search path list. More...
 
herr_t H5PLprepend (const char *search_path)
 Inserts a plugin path at the beginning of the plugin search path list. More...
 
herr_t H5PLreplace (const char *search_path, unsigned int index)
 Replaces the path at the specified index in the plugin search path list. More...
 
herr_t H5PLinsert (const char *search_path, unsigned int index)
 Inserts a path at the specified index in the plugin search path list. More...
 
herr_t H5PLremove (unsigned int index)
 Removes a plugin path at a specified index from the plugin search path list. More...
 
ssize_t H5PLget (unsigned int index, char *path_buf, size_t buf_size)
 Queries the plugin search path list at the specified index. More...
 
herr_t H5PLsize (unsigned int *num_paths)
 Retrieves the number of stored plugin paths. More...
 

Function Documentation

◆ H5PLappend()

herr_t H5PLappend ( const char *  search_path)

Inserts a plugin path at the end of the plugin search path list.

Parameters
[in]search_pathA plugin path
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLappend() inserts a plugin path at the end of the plugin search path list.

Since
1.10.1

◆ H5PLget()

ssize_t H5PLget ( unsigned int  index,
char *  path_buf,
size_t  buf_size 
)

Queries the plugin search path list at the specified index.

Parameters
[in]indexIndex
[out]path_bufPathname
[in]buf_sizeSize of path_buf
Returns
Returns the length of the path, a non-negative value, if successful; otherwise returns a negative value.

H5PLget() queries the plugin path at a specified index. If path_buf is non-NULL then it writes up to buf_size bytes into that buffer and always returns the length of the path name.

If path_buf is NULL, this function will simply return the number of characters required to store the path name, ignoring path_buf and buf_size.

If an error occurs then the buffer pointed to by path_buf (NULL or non-NULL) is unchanged and the function returns a negative value. If a zero is returned for the name's length, then there is no path name associated with the index. and the path_buf buffer will be unchanged.

Since
1.10.1

◆ H5PLget_loading_state()

herr_t H5PLget_loading_state ( unsigned int *  plugin_control_mask)

Queries the loadability of dynamic plugin types.

Parameters
[out]plugin_control_maskList of dynamic plugin types that are enabled or disabled.
A plugin bit set to 0 (zero) indicates that the dynamic plugin type is disabled.
A plugin bit set to 1 (one) indicates that the dynamic plugin type is enabled.
If the value of plugin_control_mask is negative, all dynamic plugin types are enabled.
If the value of plugin_control_mask is 0 (zero), all dynamic plugins are disabled.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugin (e.g.: filters, VOL drivers) will be loaded by the HDF5 library.

Bit positions allocated to date are specified in H5PL_type_t as follows:

typedef enum H5PL_type_t {
H5PL_type_t
Definition: H5PLpublic.h:34
@ H5PL_TYPE_FILTER
Definition: H5PLpublic.h:36
@ H5PL_TYPE_VFD
Definition: H5PLpublic.h:38
@ H5PL_TYPE_NONE
Definition: H5PLpublic.h:39
@ H5PL_TYPE_VOL
Definition: H5PLpublic.h:37
@ H5PL_TYPE_ERROR
Definition: H5PLpublic.h:35
Since
1.8.15

◆ H5PLinsert()

herr_t H5PLinsert ( const char *  search_path,
unsigned int  index 
)

Inserts a path at the specified index in the plugin search path list.

Parameters
[in]search_pathA plugin path
[in]indexIndex
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLinsert() inserts a plugin path at the specified index in the plugin search path list, moving other paths after index.

Since
1.10.1

◆ H5PLprepend()

herr_t H5PLprepend ( const char *  search_path)

Inserts a plugin path at the beginning of the plugin search path list.

Parameters
[in]search_pathA plugin path
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLprepend() inserts a plugin path at the end of the plugin search path list.

Since
1.10.1

◆ H5PLremove()

herr_t H5PLremove ( unsigned int  index)

Removes a plugin path at a specified index from the plugin search path list.

Parameters
[in]indexIndex
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLremove() removes a plugin path at the specified index and compacts the plugin search path list.

Since
1.10.1

◆ H5PLreplace()

herr_t H5PLreplace ( const char *  search_path,
unsigned int  index 
)

Replaces the path at the specified index in the plugin search path list.

Parameters
[in]search_pathA plugin path
[in]indexIndex
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLreplace() replaces a plugin path at the specified index in the plugin search path list.

Since
1.10.1

◆ H5PLset_loading_state()

herr_t H5PLset_loading_state ( unsigned int  plugin_control_mask)

Controls the loadability of dynamic plugin types.

Parameters
[in]plugin_control_maskThe list of dynamic plugin types to enable or disable.
A plugin bit set to 0 (zero) prevents use of that dynamic plugin.
A plugin bit set to 1 (one) enables use of that dynamic plugin.
Setting plugin_control_mask to a negative value enables all dynamic plugin types.
Setting plugin_control_mask to 0 (zero) disables all dynamic plugin
types.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLset_loading_state() uses one argument to enable or disable individual plugin types.

The plugin_control_mask parameter is an encoded integer in which each bit controls a specific plugin type. Bit positions allocated to date are specified in H5PL_type_t as follows:

A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type.

All dynamic plugin types can be enabled by setting plugin_control_mask to a negative value. A value of 0 (zero) will disable all dynamic plugin types.

The loading of external dynamic plugins can be controlled during runtime with an environment variable, HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the HDF5_PLUGIN_PRELOAD environment variable every time it is called. If the environment variable is set to the special :: string, all dynamic plugins are disabled.

Warning
The environment variable HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at runtime. If it is set to disable all plugin types, then it will disable them for all running programs that access the same variable instance.
Since
1.8.15

◆ H5PLsize()

herr_t H5PLsize ( unsigned int *  num_paths)

Retrieves the number of stored plugin paths.

Parameters
[out]num_pathsCurrent length of the plugin search path list
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5PLsize() retrieves the number of paths stored in the plugin search path list.

Since
1.10.1