Dynamically-loaded Plugins (H5PL)

Detailed Description

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

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.
herr_t	H5PLget_loading_state (unsigned int *plugin_control_mask)
	Queries the loadability of dynamic plugin types.
herr_t	H5PLappend (const char *search_path)
	Inserts a plugin path at the end of the plugin search path list.
herr_t	H5PLprepend (const char *search_path)
	Inserts a plugin path at the beginning of the plugin search path list.
herr_t	H5PLreplace (const char *search_path, unsigned int index)
	Replaces the path at the specified index in the plugin search path list.
herr_t	H5PLinsert (const char *search_path, unsigned int index)
	Inserts a path at the specified index in the plugin search path list.
herr_t	H5PLremove (unsigned int index)
	Removes a plugin path at a specified index from the plugin search path list.
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	H5PLsize (unsigned int *num_paths)
	Retrieves the number of stored plugin paths.

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_path

A 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]	index	Index
[out]	path_buf	Pathname
[in]	buf_size	Size 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_mask

List 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_ERROR  = -1, 
    H5PL_TYPE_FILTER = 0,  
    H5PL_TYPE_VOL    = 1,  
    H5PL_TYPE_VFD    = 2,  
    H5PL_TYPE_NONE   = 3   
} H5PL_type_t;

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_path	A plugin path
[in]	index	Index

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_path

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

index

Index

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_path	A plugin path
[in]	index	Index

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_mask

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_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:

 
typedef enum H5PL_type_t {
    H5PL_TYPE_ERROR  = -1, 
    H5PL_TYPE_FILTER = 0,  
    H5PL_TYPE_VOL    = 1,  
    H5PL_TYPE_VFD    = 2,  
    H5PL_TYPE_NONE   = 3   
} H5PL_type_t;

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_paths

Current 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