Page tree

 

JAVA

FORTRAN

C++

C

 

Link

H5P_GET_FILE_IMAGE

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

Procedure:

H5P_GET_FILE_IMAGE ( fapl_id, buf_ptr_ptr, buf_len_ptr )

Signature:

herr_t H5Pget_file_image(
            hid_t fapl_id,
            void **buf_ptr_ptr,
            size_t *buf_len_ptr
        )

  

Fortran2003 Interface: h5pget_file_image_f

Signature:
  SUBROUTINE h5pget_file_image_f(fapl_id, buf_ptr, buf_len_ptr, hdferr)
    USE iso_c_binding
    IMPLICIT NONE
    INTEGER(HID_T) , INTENT(IN)                :: fapl_id
    TYPE(C_PTR)    , INTENT(OUT), DIMENSION(*) :: buf_ptr
    INTEGER(SIZE_T), INTENT(OUT)               :: buf_len_ptr
    INTEGER        , INTENT(OUT)               :: hdferr

Inputs:
  fapl_id     - File access property list identifier.

Outputs:
  buf_ptr     - Will hold either a C_NULL_PTR or a scalar of type
                c_loc. If buf_ptr is not C_NULL_PTR, on successful
                return, buf_ptr shall contain a C pointer to a copy
                of the initial image provided in the last call to
                H5Pset_file_image_f for the supplied fapl_id, or
                buf_ptr shall contain a C_NULL_PTR if there is no
                initial image set.

  buf_len_ptr - Contains the value of the buffer parameter for
                the initial image in the supplied fapl_id. The value
                will be 0 if no initial image is set.

  hdferr      - Returns 0 if successful and -1 if fails

Parameters:
hid_t fapl_idIN: File access property list identifier
void **buf_ptr_ptrIN/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_ptrIN/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)

Description:

H5P_GET_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.

Returns:

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

Example:

Coming Soon!

History:
Release    Change
1.8.13Fortran subroutine added in this release.
1.8.9C function introduced in this release.

--- Last Modified: December 04, 2017 | 08:21 AM