Page tree

The license could not be verified: License Certificate has expired!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


Table 1. Abbreviations

Abbreviation

This abbreviation is short for:

FAPL or fapl

File Access Property List. In code samples, fapl is used.

VFD

Virtual File Driver

VFL

Virtual File Layer

Anchor
1-3
1-3
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.

1.4. Resources

See the following for more information.

The “RFC: File Image Operations” is the primary source for the information in this document.

The “Alternate File Storage Layouts and Low-level File Drivers” section is in “The HDF5 File” chapter of the HDF5 User’s Guide .

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.

Links to the “Virtual Virtual File Layer” Layer and “List List of VFL Functions” Functions documents can be found on in the “HDF5 HDF5 Technical Notes”Notes.

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.

Anchor
2-1-1
2-1-1
2.1.1. H5Pset_file_image

The 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:

...