H5PL: Plugin Interface

Plugin API Functions

The C Interfaces:

H5PLset_loading_state H5PLget_loading_state H5PLappend

H5PLget H5PLinsert  H5PLprepend

H5PLremove H5PLreplace H5PLsize

Alphabetical Listing

H5PLappend H5PLget H5PLget_loading_state

H5PLinsert  H5PLprepend  H5PLremove

H5PLreplace H5PLset_loading_state H5PLsize

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.8.19	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.8.19	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: Index.

Returns:

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

History:

Release	C
1.8.19	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.8.19	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.8.19	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.8.19	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.8.19	Function introduced in this release.

The HDF Group Help Desk: Describes HDF5 Release 1.8.20, November 2017.

Copyright by The HDF Group