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
Topics | Functions
VOL connector (H5VL)

## Detailed Description

Todo
  Describe the VOL plugin life cycle.

## 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.