Last modified: 2 May 2013
Name: H5Pget_file_image
Signature:
herr_t H5Pget_file_image( hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr )

Purpose:
Retrieves a copy of the file image designated as the initial content and structure of a file.

Motivation:
H5Pget_file_image and other HDF5 elements are used to load an image of an HDF5 file into system memory and to open that image as a regular HDF5 file. An application can then work with the file without the overhead of disk I/O.

Essential Reading:
This function is part of the file image operations feature set. It is highly recommended to study the guide “HDF5 File Image Operations” before implementing software that works with such file images.

Tthe “See Also” section below provides links to individual elements of HDF5 file image operations feature set.

Description:
H5Pget_file_image allows an application to retrieve a copy of the file image designated for a VFD to use as the initial contents of a file.

If file image callbacks are defined, H5Pget_file_image will use them when allocating and loading the buffer to return to the application (see H5Sset_file_image_callbacks). If file image callbacks are not defined, the function will use malloc and memcpy. When malloc and memcpy are used, it is the caller’s responsibility to discard the returned buffer with a call to free.

It is the responsibility of the calling application to free the buffer whose address is returned in buf_ptr_ptr. This can be accomplished with free if file image callbacks have not been set (see H5Pset_file_image_callbacks) or with the appropriate method if file image callbacks have been set.

Parameters:
hid_t fapl_id      IN: File access property list identifier.
void **buf_ptr_ptr   IN/OUT: On input, NULL or a pointer to a void*.

On successful return, if buf_ptr_ptr is not NULL, *buf_ptr_ptr will contain a pointer to a copy of the initial image provided in the last call to H5Pset_file_image for the supplied fapl_id. If no initial image has been set, *buf_ptr_ptr will be NULL.

size_t *buf_len_ptr   IN/OUT: On input, NULL or a pointer to size_t.

On successful return, if buf_len_ptr was not passed in as NULL, buf_len_ptr will return the required size in bytes of the buffer to hold the initial file image in the supplied file access property list, fapl_id. If no initial image is set, the value of *buf_len_ptr will be set to 0 (zero).

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

See Also:
H5LTopen_file_image
 
H5Fget_file_image
 
H5Pset_file_image
 
H5Pset_file_image_callbacks
H5Pget_file_image_callbacks
     HDF5 File Image Operations
     in Advanced Topics in HDF5
 
Within H5Pset_file_image_callbacks:
Callback struct   H5_file_image_callbacks_t
Callback ENUM   H5_file_image_op_t

History:
Release     Change
1.8.9 C function introduced in this release.