Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2025-11-11 The HDF5 Field Guide

- Main Page
- Getting started
- User Guide
- Reference Manual
- Cookbook
- Technical Notes
- RFCs
- Specifications
- Glossary
- Full-Text Search
- About

Loading...
Searching...
No Matches
Functions
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 | H5PLappend (const char *search_path)
| Inserts a plugin path at the end of 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 | H5PLget_loading_state (unsigned int *plugin_control_mask)
| Queries the loadability of dynamic plugin types.
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 | H5PLprepend (const char *search_path)
| Inserts a plugin path at the beginning of 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.
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 | H5PLset_loading_state (unsigned int plugin_control_mask)
| Controls the loadability of dynamic plugin types.
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