Table 1. Abbreviations
This abbreviation is short for:
FAPL or fapl
File Access Property List. In code samples, fapl is used.
Virtual File Driver
Virtual File Layer
1.3. Developer Prerequisites
Developers who use the file image operations described in this document should be proficient and experienced users of the HDF5 C Library APIs. More specifically, developers should have a working knowledge of property lists, callbacks, and virtual file drivers.
See the following for more information.
The “RFC: File Image Operations” is the primary source for the information in this document.
The H5P_SET_FAPL_CORE function call can be used to modify the file access property list so that the Memory virtual file driver, H5FD_ CORE, is used. The Memory file driver is also known as the Core file driver.
2. C API Call Syntax
The C API function calls described in this chapter fall into two categories: low-level routines that are part of the main HDF5 C Library and one high-level routine that is part of the “lite” API in the high-level wrapper library. The high-level routine uses the low-level routines and presents frequently requested functionality conveniently packaged for application developers’ use.
2.1. Low-level C API Routines
The purpose of this section is to describe the low-level C API routines that support file image operations. These routines allow an in-memory image of an HDF5 file to be opened without requiring file system I/O.
The basic approach to opening an in-memory image of an HDF5 file is to pass the image to the Core file driver, and then tell the Core file driver to open the file. We do this by using the
H5Pget/set_file_image calls. These calls allow the user to specify an initial file image.
A potential problem with the
H5Pget/set_file_image calls is the overhead of allocating and copying of large file image buffers. The callback routines enable application programs to avoid this problem. However, the use of these callbacks is complex and potentially hazardous: the particulars are discussed in the semantics and examples chapters below (see section 3.1 and section 4.1 respectively). Fortunately, use of the file image callbacks should seldom be necessary: the
H5LTopen_file_image call should address most use cases.
The property list facility in HDF5 is employed in file image operations. This facility was designed for passing data, not consumable resources, into API calls. The peculiar ways in which the file image allocation callbacks may be used allows us to avoid extending the property list structure to handle consumable resources cleanly and to avoid constructing a new facility for the purpose.
The sub-sections below describe the low-level C APIs that are used with file image operations.
H5Pset_file_image routine allows an application to provide an image for a file driver to use as the initial contents of the file. This call was designed initially for use with the Core VFD, but it can be used with any VFD that supports using an initial file image when opening a file. See the “Virtual File Driver Feature Flags” section for more information. Calling this routine makes a copy of the provided file image buffer. See the “
H5Pset_file_image_callbacks” section for more information.
The signature of
H5Pset_file_image is defined as follows:
herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len)
The parameters of
H5Pset_file_image are defined as follows: