Last modified: 18 March 2016

Name: H5Pget_virtual_filename

Signature:
ssize_t H5Pget_virtual_filename( hid_t dcpl_id, size_t index, char *name, size_t size )

Purpose:
Gets the filename of a source dataset used in the mapping.

Description:
H5Pget_virtual_filename takes the dataset creation property list for the virtual dataset, dcpl_id, the mapping index, index, the size of the filename for a source dataset, size, and retrieves the name of the file for a source dataset used in the mapping.

Up to size characters of the filename are returned in name; additional characters, if any, are not returned to the user application.

If the length of the filename, which determines the required value of size, is unknown, a preliminary call to H5Pget_virtual_filename with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the filename. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Pget_virtual_filename call, which will retrieve the actual filename.


Parameters:
hid_t dcpl_id   IN: The identifier of the virtual dataset creation property list.
size_t index   IN: Mapping index.
The value of index is 0 (zero) or greater and less than count   (0 ≤ index < count), where count is the number of mappings returned by H5Pget_virtual_count.
char *name   OUT: A buffer containing the name of the file containing the source dataset.
size_t size   IN: The size, in bytes, of the name buffer.
Must be the size of the filename in bytes plus 1 for a NULL terminator.

Returns:
Returns the length of the filename if successful; otherwise returns a negative value.

Fortran Interface: h5pget_virtual_filename_f
Signature:
  SUBROUTINE h5pget_virtual_filename_f(dcpl_id, index, name, hdferr, name_len)
    INTEGER(HID_T)  , INTENT(IN)  :: dcpl_id
    INTEGER(SIZE_T) , INTENT(IN)  :: index
    CHARACTER(LEN=*), INTENT(OUT) :: name
    INTEGER, INTENT(OUT)          :: hdferr
    INTEGER(SIZE_T), OPTIONAL     :: name_len
Optional parameters:
  name_len - The size of name needed to hold the filename. (OUT)
Inputs:
  dcpl_id - The identifier of the virtual dataset creation property list.
  index   - Mapping index.
            The value of index is 0 (zero) or greater and less than count 
            (0 ≤ index < count), where count is the number of mappings 
            returned by h5pget_virtual_count.
Outputs:
  name   - A buffer containing the name of the file containing the 
           source dataset.
  hdferr - Returns 0 if successful and -1 if fails.

See Also:
  • Virtual Dataset Overview
  • Using HDF5 Virtual Datasets
     
  •  
    Supporting functions:
  • H5Pset_layout
  • H5Pget_layout
  • H5Sis_regular_hyperslab
  • H5Sget_regular_hyperslab
  • H5Sselect_hyperslab
  • VDS functions:
  • H5Pset_virtual
  • H5Pget_virtual_count
  • H5Pget_virtual_vspace
  • H5Pget_virtual_srcspace
  • H5Pget_virtual_dsetname
  • H5Pset_virtual_printf_gap
  • H5Pget_virtual_printf_gap
  • H5Pset_virtual_view
  • H5Pget_virtual_view

  • History:
    Release     Change
    1.10.0 C function introduced with this release.