H5PL: Plugin Interface

Plugin API Functions

The C Interfaces:

H5PLset_loading_state H5PLget_loading_state

Last modified: 2 September 2015

Name: H5PLget_loading_state

Signature:

herr_t H5PLget_loading_state( int *plugin_flags )

Purpose:

Query state of the loading of dynamic plugins.

Description:

H5PLget_loading_state retrieves the state of the dynamic plugins flag, plugin_flags.

Types of plugins that are subject to programmatic control are listed in the definition of the H5PL_type_t ENUM. That list is presented in the “Plugin Type/Bit Position” table in the H5PLset_loading_state reference manual entry.

Parameters:

int plugin_flags

OUT: List of dynamic plugin types that are enabled or disabled. A plugin bit set to 0 (zero) indicates that that dynamic plugin is disabled. A plugin bit set to 1 (one) indicates that that dynamic plugin is enabled. If the value of plugin_flags is negative, all dynamic plugins are enabled. If the value of plugin_flags is 0 (zero), all dynamic plugins are disabled.

Returns:

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

Example Usage:

/* Disable plugin X: Requires user to negate the state 
 * with a 0 in bit position X and AND it with the result 
 * from an H5PLget_loading_state call. */

H5PLget_loading_state(&curr_setting);
int new_setting = curr_setting & ~H5PL_FILTER_PLUGIN ;
H5PLset_loading_state (new_setting);
    

Fortran Interface:

None.

See Also:

H5PLset_loading_state

“Dynamic Plugins in HDF5”

History:

Release	C
1.8.15	Function introduced in this release.

Last modified: 28 August 2015

Name: H5PLset_loading_state

Signature:

herr_t H5PLset_loading_state( int plugin_flags )

Purpose:

Control the loading of dynamic plugins.

Motivation:

The loading of external dynamic plugins can be controlled during runtime with an environment variable, HDF5_PLUGIN_PRELOAD. The environment variable can control the loading of dynamic filters at runtime, but it will disable it for all running programs that access that variable using the library.

H5PLset_loading_state controls the loading of external dynamic plugins during program execution.

Description:

H5PLset_loading_state uses one argument to enable or disable individual plugins.

The plugin_flags parameter is an encoded integer in which each bit controls a specific plugin or class of plugins. Bit positions allocated to date are listed in the “Plugin Type/Bit Position” table below.

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

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

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 will be disabled.

Note:

The classes of plugins subject to programmatic control are specified in the H5PL_type_t ENUM. Since only dynamically loaded filter plugins are currently subject to programmatic control, only one plugin type is defined:

	Plugin Type	Bit Position
	H5PL_TYPE_FILTER	0

Additional values may be added to the H5PL_type_t ENUM as programmatic control is implemented for other plugin types.

Parameters:

int plugin_flags

IN: The 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_flags to a negative value enables all dynamic plugins. Setting plugin_flags to 0 (zero) disables all dynamic plugins.

Returns:

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

Example Usage:

/* Disable plugin X: Requires user to negate the state 
 * with a 0 in bit position X and AND it with the result 
 * from an H5PLget_loading_state call. */

H5PLget_loading_state(&curr_setting);
int new_setting = curr_setting & ~H5PL_FILTER_PLUGIN ;
H5PLset_loading_state (new_setting);
    

Fortran90 Interface:

None.

See Also:

H5PLget_loading_state

“Dynamic Plugins in HDF5”

History:

Release	C
1.8.15	Function introduced in this release.

The HDF Group Help Desk: Describes HDF5 Release 1.8.18, November 2016.

Copyright by The HDF Group