Last modified: 26 April 2016
Name: H5Pset_efile_prefix
Signature:
  `herr_t H5Pset_efile_prefix( hid_t dapl_id, const char *prefix )`
Purpose:
  Sets the external dataset storage file prefix in the dataset access property list.
Description:
  `H5Pset_efile_prefix` sets the prefix used to locate raw data files for a dataset that uses external storage. This prefix can provide either an absolute path or a relative path to the external files.

  `H5Pset_efile_prefix` is used in conjunction with `H5Pset_external` to control the behavior of the HDF5 Library when searching for the raw data files associated with a dataset that uses external storage:

  - The default behavior of the library is to search for the dataset’s external storage raw data files in the same directory as the HDF5 file which contains the dataset.
  - If the prefix is set to an absolute path, the target directory will be searched for the dataset’s external storage raw data files.
  - If the prefix is set to a relative path, the target directory, relative to the current working directory, will be searched for the dataset’s external storage raw data files.
  - If the prefix is set to a relative path that begins with the special token `${ORIGIN}`, that directory, relative to the HDF5 file containing the dataset, will be searched for the dataset’s external storage raw data files.

  The `HDF5_EXTFILE_PREFIX` environment variable can be used to override the above behavior (the environment variable supersedes the API call). Setting the variable to a path string and calling `H5Dcreate` or `H5Dopen` is the equivalent of calling `H5Pset_efile_prefix` and calling the same create or open function. The environment variable is checked at the time of the create or open action and copied so it can be safely changed after the `H5Dcreate` or `H5Dopen` call.

  Calling `H5Pset_efile_prefix` with `prefix` set to `NULL` or the empty string returns the search path to the default. The result would be the same as if `H5Pset_efile_prefix` had never been called.

Notes:
  If the external file prefix is not an absolute path and the HDF5 file is moved, the external storage files will also need to be moved so they can be accessed at the new location.

  As stated above, the use of the `HDF5_EXTFILE_PREFIX` environment variable overrides any property list setting. `H5Pset_efile_prefix` and `H5Pget_efile_prefix`, being property functions, set and retrieve only the property list setting; they are unaware of the environment variable.

  On Windows, the prefix must be an ASCII string since the Windows standard C library’s I/O functions cannot handle UTF-8 file names.

Parameters:

  `hid_t dapl_id` | `` | IN: Dataset access property list identifier
  `const char *prefix` | `` | IN: Dataset external storage prefix in UTF-8 or ASCII (Path and filename must be ASCII on Windows systems.)

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran Interface:
  None
See Also:

`H5Pget_efile_prefix` `H5Pset_external`

History:

  Release | Change
  1.10.0 and 1.8.17 | C function introduced in these releases.