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

## Detailed Description

## Data Structures
struct | H5VL_class_t

## Functions
herr_t | H5VLclose_lib_context (void *context)
| Closes the internal state of the HDF5 library.
hid_t | H5VLget_file_type (void *file_obj, hid_t connector_id, hid_t dtype_id)
void * | H5VLobject (hid_t obj_id)
herr_t | H5VLopen_lib_context (void **context)
| Opens a new internal context for the HDF5 library.
hid_t | H5VLregister_connector (const H5VL_class_t *cls, hid_t vipl_id)
| Registers a new VOL connector.

## Function Documentation

## ◆ H5VLclose_lib_context()

herr_t H5VLclose_lib_context | ( | void * | context | ) |

Closes the internal state of the HDF5 library.

Parameters

  [in] | context | library's context

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

Closes the internal state of the HDF5 library, undoing the effects of H5VLopen_lib_context(). This function must be called as a pair with H5VLopen_lib_context(). It can be invoked before, after, or independently of H5VLfree_lib_state().

Note
  This routine is exclusively for authors of HDF5 VOL connectors. It is not part of the public HDF5 APIs for HDF5 application developers.

Since
  2.0.0

## ◆ H5VLget_file_type()

hid_t H5VLget_file_type | ( | void * | file_obj,
|  | hid_t | connector_id,
|  | hid_t | dtype_id )

## ◆ H5VLobject()

void * H5VLobject | ( | hid_t | obj_id | ) |

## ◆ H5VLopen_lib_context()

herr_t H5VLopen_lib_context | ( | void ** | context | ) |

Opens a new internal context for the HDF5 library.

Parameters

  [out] | context | library's context

Returns
  Returns a non-negative value if `*context` is set; otherwise returns negative value if `*context` is unset.

Opens a new internal context for the HDF5 library. The context returned (via the OUT parameter) must be passed to H5VLclose_lib_context() to conclude the library's context and release resources.

Note
  This routine is exclusively for authors of HDF5 VOL connectors. It is not part of the public HDF5 APIs for HDF5 application developers.

Since
  2.0.0

## ◆ H5VLregister_connector()

hid_t H5VLregister_connector | ( | const H5VL_class_t * | cls,
|  | hid_t | vipl_id )

Registers a new VOL connector.

Parameters

  [in] | cls | A pointer to the plugin structure to register
  [in] | vipl_id | VOL initialization property list identifier

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

H5VLregister_connector() registers a new VOL connector 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 the VOL documentation.

H5VL_class_t is defined in H5VLconnector.h in the source code. It contains class information for each VOL connector:

typedef struct H5VL_class_t {
/* Overall connector fields & callbacks */
unsigned version;
H5VL_class_value_t value;
const char *name;
unsigned conn_version;
uint64_t cap_flags;
herr_t (*initialize)(hid_t vipl_id);
herr_t (*terminate)(void);
/* VOL framework */
H5VL_info_class_t info_cls;
H5VL_wrap_class_t wrap_cls;
/* Data Model */
H5VL_attr_class_t attr_cls;
H5VL_dataset_class_t dataset_cls;
H5VL_datatype_class_t datatype_cls;
H5VL_file_class_t file_cls;
H5VL_group_class_t group_cls;
H5VL_link_class_t link_cls;
H5VL_object_class_t object_cls;
/* Infrastructure / Services */
H5VL_introspect_class_t introspect_cls;
H5VL_request_class_t request_cls;
H5VL_blob_class_t blob_cls;
H5VL_token_class_t token_cls;
/* Catch-all */
herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id,
void **req);
} H5VL_class_t;

Since
  1.12.0