Last modified: 2 May 2014
Name: H5Fget_file_image
Signature:
  ssize_t `H5Fget_file_image`( hid_t `file_id`, void *`buf_ptr`, size_t *`buf_len` )

Purpose:
  Retrieves a copy of the image of an existing, open file.

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

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.

Description:
  `H5Fget_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 `H5Fget_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 unkown, it can be safely determined with an initial `H5Fget_file_image` call with `buf_ptr` set to `NULL`. The file image can then be retrieved with a second `H5Fget_file_image` with `buf_len` set to the initial call’s return value.

  While the current file size can also be retrieved with `H5Fget_filesize`, that call may produce a larger value than is needed. The value returned by `H5Fget_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 `H5Fget_file_image` and it often produces a value that is more appropriate for the size of a file image buffer.

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 `buf_ptr` is `NULL`, no data will be copied but the function’s return value will still indicate the buffer size required (or a negative value on error).
  size_t *`buf_len` |  | IN: Size of the supplied buffer

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:
  `H5Pget_file_image` will fail, returning a negative value, if the file is too large for the supplied buffer.

Fortran2003 Interface: h5fget_file_image_f

See Also:

  `H5LTopen_file_image` `H5Pset_file_image` `H5Pget_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.13 | Fortran subroutine added in this release.
  1.8.9 | C function introduced in this release.