HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

H5PL: Plugin Interface

Plugin API Functions

The Plugin interface provides for programmatic control of dynamically loaded plugins.

The C Interfaces:

Alphabetical Listing
             


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.

Last modified: May 2017
Name: H5PLappend
Signature:
herr_t H5PLappend( const char *plugin_path )

Purpose:
Insert a plugin path at the end of the list.

Description:
H5PLappend inserts a plugin path at the end of the list.

Parameters:
const char *plugin_path     IN: The plugin path.

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

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLget
Signature:
ssize_t H5PLget( unsigned int index, char *pathname, size_t size )

Purpose:
Query the plugin path at the specified index.

Description:
H5PLget queries the plugin path at a specified index. If pathname is non-NULL then it writes up to size bytes into that buffer and always returns the length of the pathname. Otherwise size is ignored and the function does not store the pathname, just returning the number of characters required to store the pathname. If an error occurs then the buffer pointed to by pathname (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 pathname associated with the index.

Parameters:
unsigned int  index     IN: Index.
char  *pathname     OUT: Pathname.
size_t  Size     IN: Size.

Returns:
Returns the length of the path, a non-negative value, if successful; otherwise returns a negative value.

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLinsert
Signature:
herr_t H5PLinsert( const char *plugin_path, unsigned int index )

Purpose:
Insert a plugin path at the specified index.

Description:
H5PLinsert inserts a plugin path at the specified index, moving other paths after the index.

Parameters:
const char *plugin_path     IN: The plugin path.
unsigned int  index     IN: The index.

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

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLprepend
Signature:
herr_t H5PLprepend( const char *plugin_path )

Purpose:
Insert a plugin path at the beginning of the list.

Description:
H5PLprepend inserts a plugin path at the beginning of the list.

Parameters:
const char *plugin_path     IN: The plugin path.

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

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLremove
Signature:
herr_t H5PLremove( unsigned int index )

Purpose:
Remove the plugin path at the specified index.

Description:
H5PLremove removes a plugin path at the specified index and compacts the list.

Parameters:
unsigned int  index     IN: Index.

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

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLreplace
Signature:
herr_t H5PLreplace( const char *plugin_path, unsigned int index )

Purpose:
Replace the plugin path at the specified index.

Description:
H5PLreplace replaces a plugin path at the specified index.

Parameters:
const char *plugin_path     IN: The plugin path.
unsigned int  index     IN: Index.

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

History:
Release     C
1.10.1 Function introduced in this release.

Last modified: May 2017
Name: H5PLsize
Signature:
herr_t H5PLsize( unsigned int *listsize )

Purpose:
Query the size of the current list of plugin paths.

Description:
H5PLsize queries the size of the current list of plugin paths.

Parameters:
unsigned int  *listsize     IN: Current list of plugin paths.

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

History:
Release     C
1.10.1 Function introduced in this release.

HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

The HDF Group Help Desk:
Describes HDF5 Release 1.10.
  Copyright by The HDF Group