- Created by Mike McGreevy, last modified by Barbara Jones on May 17, 2019
H5F_GET_FILE_IMAGE
Retrieves a copy of the image of an existing, open file
Procedure:
H5F_GET_FILE_IMAGE (file_id, buf_ptr, buf_len)
Signature:
ssize_t H5Fget_file_image( hid_t file_id, void *buf_ptr, size_t buf_len )
SUBROUTINE h5fget_file_image_f(file_id, buf_ptr, buf_len, hdferr, buf_size)
USE, INTRINSIC :: ISO_C_BINDING
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: file_id
TYPE(C_PTR) , INTENT(INOUT) :: buf_ptr
INTEGER(SIZE_T), INTENT(IN) :: buf_len
INTEGER , INTENT(OUT) :: hdferr
INTEGER(SIZE_T), INTENT(OUT) , OPTIONAL :: buf_size
Parameters:
hid_t file_id | IN: Target file identifier |
void *buf_ptr | IN: Pointer to the buffer into which the image of the HDF5 file is to be copied If |
size_t buf_len | IN: Size of the supplied buffer |
Description:
H5F_GET_FILE_IMAGE retrieves a copy of the image of an existing, open file. This routine can be used with files opened using the SEC2 (or POSIX), STDIO, and Core (or Memory) virtual file drivers (VFDs).
If the return value of H5F_GET_FILE_IMAGE is a positive value, it will be the length in bytes of the buffer required to store the file image. So if the file size is unknown, it can be safely determined with an initial H5F_GET_FILE_IMAGE call with buf_ptr set to NULL. The file image can then be retrieved with a second H5F_GET_FILE_IMAGE call with buf_len set to the initial call’s return value.
While the current file size can also be retrieved with H5F_GET_FILESIZE, that call may produce a larger value than is needed. The value returned by H5F_GET_FILESIZE includes the user block, if it exists, and any unallocated space at the end of the file. It is safe in all situations to get the file size with H5F_GET_FILE_IMAGE and it often produces a value that is more appropriate for the size of a file image buffer.
Recommended 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 using this feature set.
See the “See Also” section below for links to other elements of HDF5 file image operations.
Returns:
If successful, returns the size in bytes of the buffer required to store the file image if successful; otherwise returns a negative value.
Failure Modes: H5P_GET_FILE_IMAGE will fail, returning a negative value, if the file is too large for the supplied buffer.
Example:
Coming soon!
See Also:
| H5LT_OPEN_FILE_IMAGE H5P_SET_FILE_IMAGE H5P_GET_FILE_IMAGE H5P_SET_FILE_IMAGE_CALLBACKS H5P_GET_FILE_IMAGE_CALLBACKS | Within H5P_SET_FILE_IMAGE_CALLBACKS: |
History:
| Release | Change |
|---|---|
| 1.8.13 | Fortran subroutine added in this release. |
| 1.8.9 | C function introduced in this release. |
--- Last Modified: May 17, 2019 | 02:58 PM