12.4.18.4 Getting file names

The function PL_get_file_name() provides access to Prolog filenames and its file-search mechanism described with absolute_file_name/3. Its existence is motivated to realise a uniform interface to deal with file properties, search, naming conventions, etc., from foreign code.

bool PL_get_file_name(term_t spec, char **name, int flags)

Translate a Prolog term into a file name. The name is stored in the buffer stack described with the PL_get_chars() option BUF_STACK, which is popped upon return from the foreign predicate to Prolog. Conversion from the internal UNICODE encoding is done using standard C library functions. flags is a bit-mask controlling the conversion process. On failure, PL_FILE_NOERRORS controls whether an exception is raised. Options are:

PL_FILE_ABSOLUTE

Return an absolute path to the requested file.

PL_FILE_OSPATH

Return the name using the hosting OS conventions. On MS-Windows, \ is used to separate directories rather than the canonical /.

PL_FILE_SEARCH

Invoke absolute_file_name/3. This implies rules from file_search_path/2 are used.

PL_FILE_EXIST

Demand the path to refer to an existing entity.

PL_FILE_READ

Demand read-access on the result.

PL_FILE_WRITE

Demand write-access on the result.

PL_FILE_EXECUTE

Demand execute-access on the result.

PL_FILE_NOERRORS

Do not raise any exceptions.

bool PL_get_file_nameW(term_t spec, wchar_t **name, int flags)

Same as PL_get_file_name(), but returns the filename as a wide-character string. This is intended for Windows to access the Unicode version of the Win32 API. Note that the flag PL_FILE_OSPATH must be provided to fetch a filename in OS native (e.g., C:\x\y) notation.