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

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
VOL connector (H5VL)

## Detailed Description

Use the functions in this module to manage HDF5 Virtual Object Layer (VOL) connectors.

VOL connectors provide an abstraction layer for storage operations, enabling HDF5 to work with different storage backends while maintaining the familiar HDF5 API. This module provides functions for registering, configuring, and managing VOL connector plugins.

### VOL Connector Life Cycle

VOL connectors can be implemented as dynamically loaded plugins, statically linked libraries, or built into the HDF5 library itself. Throughout this documentation, "VOL connector" refers to the connector implementation regardless of how it is deployed.

VOL connectors follow a well-defined life cycle from loading to cleanup:

1. Discovery and Loading

   - For dynamically loaded plugins: The library searches the plugin path (default: /usr/local/hdf5/lib/plugin on POSIX, ALLUSERSPROFILE%/hdf5/lib/plugin on Windows)
   - Plugin path can be overridden using the HDF5_PLUGIN_PATH environment variable
   - For statically linked connectors: The connector is available immediately when the library loads
   - For internal connectors: Built into the HDF5 library (e.g., the native VOL connector)

2. Registration

   - Before use, connectors must be registered with the library using:
     - H5VLregister_connector() - Registers a new VOL connector
     - H5VLregister_connector_by_name() - Register by connector name
     - H5VLregister_connector_by_value() - Register by connector-specific value
   - Registration loads the connector and returns an HDF5 identifier (hid_t)
   - Many connectors provide initialization functions that handle registration automatically
   - Registration can also occur automatically via the HDF5_VOL_CONNECTOR environment variable

3. Configuration

   - The connector is set in a file access property list (fapl) using:
     - H5Pset_vol() - Generic method using connector ID and optional configuration
     - Connector-specific functions (e.g., H5Pset_fapl_<name>()) - Often more convenient
     - HDF5_VOL_CONNECTOR environment variable - Sets the default connector for all file opens
   - Configuration may include connector-specific parameters passed via info structs or parameter strings
   - Parameter strings can be parsed using H5VLconnector_str_to_info()

4. Active Use

   - When a file is opened or created with a configured fapl, the specified VOL connector handles all storage operations
   - All API calls that manipulate storage (create, open, read, write, etc.) are forwarded to the connector's callbacks
   - The connector remains active for the lifetime of all files opened with it
   - Multiple different connectors can be active simultaneously for different files

5. Query and Introspection

   - H5Pget_vol_id() retrieves the connector ID from a fapl
   - H5Pget_vol_info() retrieves connector-specific configuration information
   - H5VLget_connector_name() retrieves the connector's registered name
   - H5VLis_connector_registered_by_name() checks if a connector is registered by name
   - H5VLis_connector_registered_by_value() checks if a connector is registered by value
   - H5VLquery_optional() determines support for optional operations

6. Cleanup and Unregistration
   - Connector IDs can be closed using:
     - H5VLunregister_connector() - Unregister a connector
     - H5VLclose() - Close a connector ID (same internal implementation)
   - The library maintains reference counts on connector IDs and will not actually close them until the reference count reaches zero
   - It is safe to close connector IDs after use, even while files opened with that connector remain open
   - The library automatically unloads all connectors when it shuts down
   - The native VOL connector cannot be unloaded and is always available
   - Connector-specific info structures should be freed using H5VLfree_connector_info()

See also
  H5VL_UG

## Topics
| Definitions
| Native VOL
| Pass-through VOL
| VOL Developer

## Functions
herr_t | H5VLclose (hid_t connector_id)
| Closes a VOL connector identifier.
hid_t | H5VLget_connector_id (hid_t obj_id)
| Retrieves the VOL connector identifier for a given object identifier.
hid_t | H5VLget_connector_id_by_name (const char *name)
| Retrieves the identifier for a registered VOL connector name.
hid_t | H5VLget_connector_id_by_value (H5VL_class_value_t connector_value)
| Retrieves the identifier for a registered VOL connector value.
ssize_t | H5VLget_connector_name (hid_t id, char *name, size_t size)
| Retrieves a connector name for a VOL.
htri_t | H5VLis_connector_registered_by_name (const char *name)
| Tests whether a VOL class has been registered under a certain name.
htri_t | H5VLis_connector_registered_by_value (H5VL_class_value_t connector_value)
| Tests whether a VOL class has been registered for a given value.
herr_t | H5VLobject_is_native (hid_t obj_id, bool *is_native)
| Determines whether an object ID represents a native VOL connector object.
herr_t | H5VLquery_optional (hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags)
| Determine if a VOL connector supports a particular optional callback operation.
hid_t | H5VLregister_connector_by_name (const char *connector_name, hid_t vipl_id)
| Registers a new VOL connector by name.
hid_t | H5VLregister_connector_by_value (H5VL_class_value_t connector_value, hid_t vipl_id)
| Registers a new VOL connector by value.
herr_t | H5VLunregister_connector (hid_t connector_id)
| Removes a VOL connector identifier from the library.
hid_t | H5VLwrap_register (void *obj, H5I_type_t type)
| Wrap an internal object with a "wrap context" and register an hid_t for the resulting object.

## Function Documentation

## ◆ H5VLclose()

herr_t H5VLclose | ( | hid_t | connector_id | ) |

Closes a VOL connector identifier.

Parameters

  [in] | connector_id | Connector identifier

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

H5VLclose() closes a VOL connector identifier. This does not affect the file access property lists which have been defined to use this VOL connector or files which are already opened under this connector.

Since
  1.12.0

## ◆ H5VLget_connector_id()

hid_t H5VLget_connector_id | ( | hid_t | obj_id | ) |

Retrieves the VOL connector identifier for a given object identifier.

Parameters

  [in] | obj_id | Object identifier

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id() retrieves the registered VOL connector identifier for the specified object identifier `obj_id`. The VOL connector identifier must be closed with H5VLclose() when no longer in use.

Since
  1.12.0

## ◆ H5VLget_connector_id_by_name()

hid_t H5VLget_connector_id_by_name | ( | const char * | name | ) |

Retrieves the identifier for a registered VOL connector name.

Parameters

  [in] | name | Connector name

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id_by_name() retrieves the identifier for a registered VOL connector with the name `name`. The identifier must be closed with H5VLclose() when no longer in use.

Since
  1.12.0

## ◆ H5VLget_connector_id_by_value()

hid_t H5VLget_connector_id_by_value | ( | H5VL_class_value_t | connector_value | ) |

Retrieves the identifier for a registered VOL connector value.

Parameters

  [in] | connector_value | Connector value

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id_by_value() retrieves the identifier for a registered VOL connector with the value `connector_value`. The identifier will need to be closed by H5VLclose().

`connector_value` has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

Since
  1.12.0

## ◆ H5VLget_connector_name()

ssize_t H5VLget_connector_name | ( | hid_t | id,
|  | char * | name,
|  | size_t | size )

Retrieves a connector name for a VOL.

Parameters

  [in] | id | Object identifier or file identifier
  [out] | name | Connector name
  [in] | size | Maximum length of the name to retrieve

Returns
  Returns the length of the connector name on success, and a negative value on failure.

H5VLget_connector_name() retrieves up to `size` elements of the VOL name `name` associated with the object or file identifier `id`.

Passing in a NULL pointer for size will return the size of the connector name. This can be used to determine the size of the buffer to allocate for the name.

Since
  1.12.0

## ◆ H5VLis_connector_registered_by_name()

htri_t H5VLis_connector_registered_by_name | ( | const char * | name | ) |

Tests whether a VOL class has been registered under a certain name.

Parameters

  [in] | name | Alleged name of connector

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5VLis_connector_registered_by_name() tests whether a VOL class has been registered or not, according to the supplied connector name `name`.

Since
  1.12.0

## ◆ H5VLis_connector_registered_by_value()

htri_t H5VLis_connector_registered_by_value | ( | H5VL_class_value_t | connector_value | ) |

Tests whether a VOL class has been registered for a given value.

Parameters

  [in] | connector_value | Connector value

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5VLis_connector_registered_by_value() tests whether a VOL class has been registered, according to the supplied connector value `connector_value`.

`connector_value` has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

Since
  1.12.0

## ◆ H5VLobject_is_native()

herr_t H5VLobject_is_native | ( | hid_t | obj_id,
|  | bool * | is_native )

Determines whether an object ID represents a native VOL connector object.

Parameters

  [in] | obj_id | Object identifier
  [out] | is_native | Boolean determining whether object is a native VOL connector object

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

Since
  1.12.2

## ◆ H5VLquery_optional()

herr_t H5VLquery_optional | ( | hid_t | obj_id,
|  | H5VL_subclass_t | subcls,
|  | int | opt_type,
|  | uint64_t * | flags )

Determine if a VOL connector supports a particular optional callback operation.

Parameters

  [in] | obj_id | Object identifier
  [in] | subcls | VOL subclass
  [in] | opt_type | Option type
  [out] | flags | Operation flags

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

Since
  1.12.1

## ◆ H5VLregister_connector_by_name()

hid_t H5VLregister_connector_by_name | ( | const char * | connector_name,
|  | hid_t | vipl_id )

Registers a new VOL connector by name.

Parameters

  [in] | connector_name | Connector name
  [in] | vipl_id | VOL initialization property list identifier

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLregister_connector_by_name() registers a new VOL connector with the name `connector_name` as a member of the virtual object layer class. This VOL connector identifier is good until the library is closed or the connector is unregistered.

`vipl_id` is either H5P_DEFAULT or the identifier of a VOL initialization property list of class H5P_VOL_INITIALIZE created with H5Pcreate(). When created, this property list contains no library properties. If a VOL connector author decides that initialization-specific data are needed, they can be added to the empty list and retrieved by the connector in the VOL connector's initialize callback. Use of the VOL initialization property list is uncommon, as most VOL-specific properties are added to the file access property list via the connector's API calls which set the VOL connector for the file open/create. For more information, see VOL documentation.

Since
  1.12.0

## ◆ H5VLregister_connector_by_value()

hid_t H5VLregister_connector_by_value | ( | H5VL_class_value_t | connector_value,
|  | hid_t | vipl_id )

Registers a new VOL connector by value.

Parameters

  [in] | connector_value | Connector value
  [in] | vipl_id | VOL initialization property list identifier

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLregister_connector_by_value() registers a new VOL connector with value connector_value as a member of the virtual object layer class. This VOL connector identifier is good until the library is closed or the connector is unregistered.

`connector_value` has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

`vipl_id` is either H5P_DEFAULT or the identifier of a VOL initialization property list of class H5P_VOL_INITIALIZE created with H5Pcreate(). When created, this property list contains no library properties. If a VOL connector author decides that initialization-specific data are needed, they can be added to the empty list and retrieved by the connector in the VOL connector's initialize callback. Use of the VOL initialization property list is uncommon, as most VOL-specific properties are added to the file access property list via the connector's API calls which set the VOL connector for the file open/create. For more information, see the VOL documentation.

Since
  1.12.0

## ◆ H5VLunregister_connector()

herr_t H5VLunregister_connector | ( | hid_t | connector_id | ) |

Removes a VOL connector identifier from the library.

Parameters

  [in] | connector_id | Connector identifier

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

H5VLunregister_connector() removes a VOL connector identifier from the library. This does not affect the file access property lists which have been defined to use the VOL connector or any files which are already opened with this connector.

Attention
  H5VLunregister_connector() will fail if attempting to unregister the native VOL connector.

Since
  1.12.0

## ◆ H5VLwrap_register()

hid_t H5VLwrap_register | ( | void * | obj,
|  | H5I_type_t | type )

Wrap an internal object with a "wrap context" and register an hid_t for the resulting object.

Parameters

  [in] | obj | VOL object.
  [in] | type | VOL-managed object class. Allowable values are: H5I_FILE H5I_GROUP H5I_DATATYPE H5I_DATASET H5I_MAP H5I_ATTR

Returns
  Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

Note
  This routine is mainly targeted toward wrapping objects for iteration routine callbacks (i.e. the callbacks from H5Aiterate*, H5Literate* / H5Lvisit*, and H5Ovisit* ). Using it in an application will return an error indicating the API context isn't available or can't be retrieved.