Last modified: 5 May 2014
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.

  The “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.

  Note/Warning: This seems like one that might not require a note or warning.
  Silent failure or unintended consequences that might go unnoticed, for example.

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 pointer to a buffer that contains the file image. 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 a buffer specifying the required size of the buffer to hold the file image. 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.

Failure Modes:
  None known to date.

Fortran2003 Interface: h5pget_file_image_f

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