4.34 File System Interaction

access_file(+File, +Mode)
True if File exists and can be accessed by this prolog process under mode Mode. Mode is one of the atoms read, write, append, exist, none or execute. File may also be the name of a directory. Fails silently otherwise. access_file(File, none) simply succeeds without testing anything.

If `Mode' is write or append, this predicate also succeeds if the file does not exist and the user has write-access to the directory of the specified location.

exists_file(+File)
True if File exists and is a regular file. This does not imply the user has read and/or write permission for the file.
file_directory_name(+File, -Directory)
Extracts the directory-part of File. The returned Directory name does not end in /. There are two special cases. The directory-name of / is / itself and the directory-name if File does not contain any / characters is ..
file_base_name(+File, -BaseName)
Extracts the filename part from a path specification. If File does not contain any directory separators, File is returned.
same_file(+File1, +File2)
True if both filenames refer to the same physical file. That is, if File1 and File2 are the same string or both names exist and point to the same file (due to hard or symbolic links and/or relative vs. absolute paths).
exists_directory(+Directory)
True if Directory exists and is a directory. This does not imply the user has read, search and or write permission for the directory.
delete_file(+File)
Remove File from the file system.
rename_file(+File1, +File2)
Rename File1 into File2. The semantics is compatible to the POSIX semantics of the rename() system call as far as the operating system allows. if File2 exists, the operation succeeds (except for possible permission errors) and is atomic (meaning there is no window where File2 does not exist).
size_file(+File, -Size)
Unify Size with the size of File in bytes.
time_file(+File, -Time)
Unify the last modification time of File with Time. Time is a floating point number expressing the seconds elapsed since Jan 1, 1970. See also convert_time/[2,8] and get_time/1.
absolute_file_name(+File, -Absolute)
Expand a local file-name into an absolute path. The absolute path is canonised: references to . and .. are deleted. This predicate ensures that expanding a file-name it returns the same absolute path regardless of how the file is addressed. SWI-Prolog uses absolute file names to register source files independent of the current working directory. See also absolute_file_name/3. See also absolute_file_name/3 and expand_file_name/2.
absolute_file_name(+Spec, +Options, -Absolute)
Converts the given file specification into an absolute path. Option is a list of options to guide the conversion:
extensions(ListOfExtensions)
List of file-extensions to try. Default is ''. For each extension, absolute_file_name/3 will first add the extension and then verify the conditions imposed by the other options. If the condition fails, the next extension of the list is tried. Extensions may be specified both as ..ext or plain ext.
relative_to(+FileOrDir)
Resolve the path relative to the given directory or directory the holding the given file. Without this option, paths are resolved relative to the working directory (see working_directory/2) or, if Spec is atomic and absolute_file_name/[2,3] is executed in a directive, it uses the current source-file as reference.
access(Mode)
Imposes the condition access_file(File, Mode). Mode is on of read, write, append, exist or none. See also access_file/2.
file_type(Type)
Defines extensions. Current mapping: txt implies [''], prolog implies ['.pl', ''], executable implies ['.so', ''], qlf implies ['.qlf', ''] and directory implies ['']. The file-type source is an alias for prolog for compatibility with SICStus Prolog. See also prolog_file_type/2.
file_errors(fail/error)
If error (default), throw and existence_error exception if the file cannot be found. If fail, stay silent.62Silent operation was the default up to version 3.2.6.
solutions(first/all)
If first (default), the predicates leaves no choice-point. Otherwise a choice-point will be left and backtracking may yield more solutions.
expand(true/false)
If true (default is false) and Spec is atomic, call expand_file_name/2 followed by member/2 on Spec before proceeding. This is a SWI-Prolog extension.

The Prolog flag verbose_file_search can be set to true to help debugging Prolog's search for files.

Compatibility considerations with common argument-order in ISO as well as SICStus absolute_file_name/3 forced us to be flexible here. If the last argument is a list and the 2nd not, the arguments are swapped, making the call absolute_file_name(+Spec, -Path, +Options) valid as well.

is_absolute_file_name(+File)
True if File specifies and absolute path-name. On Unix systems, this implies the path starts with a `/'. For Microsoft based systems this implies the path starts with <letter>:. This predicate is intended to provide platform-independent checking for absolute paths. See also absolute_file_name/2 and prolog_to_os_filename/2.
file_name_extension(?Base, ?Extension, ?Name)
This predicate is used to add, remove or test filename extensions. The main reason for its introduction is to deal with different filename properties in a portable manner. If the file system is case-insensitive, testing for an extension will be done case-insensitive too. Extension may be specified with or without a leading dot (.). If an Extension is generated, it will not have a leading dot.
directory_files(+Directory, -Entries)
Unifies Entries with a list of entries in Directory. Each member of Entries is an atom denoting an entry relative to Directory. Entries contains all entries, including hidden files and, if supplied by the OS, the special entries . and ... See also expand_file_name/2.63This predicate should be considered a misnomer because it returns entries rather than files. We stick to this name for compatibility with e.g., SICStus, Ciao and YAP.
expand_file_name(+WildCard, -List)
Unify List with a sorted list of files or directories matching WildCard. The normal Unix wildcard constructs `?', `*', `[ ... ]' and `{...}' are recognised. The interpretation of `{...}' is interpreted slightly different from the C shell (csh(1)). The comma separated argument can be arbitrary patterns, including `{...}' patterns. The empty pattern is legal as well: `{.pl,}' matches either `.pl' or the empty string.

If the pattern does contains wildcard characters, only existing files and directories are returned. Expanding a `pattern' without wildcard characters returns the argument, regardless on whether or not it exists.

Before expanding wildcards, the construct $var is expanded to the value of the environment variable var and a possible leading ~ character is expanded to the user's home directory.64On Windows, the home directory is determined as follows: if the environment variable HOME exists, this is used. If the variables HOMEDRIVE and HOMEPATH exist (Windows-NT), these are used. At initialisation, the system will set the environment variable HOME to point to the SWI-Prolog home directory if neither HOME nor HOMEPATH and HOMEDRIVE are defined.

prolog_to_os_filename(?PrologPath, ?OsPath)
Converts between the internal Prolog pathname conventions and the operating-system pathname conventions. The internal conventions are Unix and this predicates is equivalent to =/2 (unify) on Unix systems. On DOS systems it will change the directory-separator, limit the filename length map dots, except for the last one, onto underscores.
read_link(+File, -Link, -Target)
If File points to a symbolic link, unify Link with the value of the link and Target to the file the link is pointing to. Target points to a file, directory or non-existing entry in the file system, but never to a link. Fails if File is not a link. Fails always on systems that do not support symbolic links.
[deprecated]tmp_file(+Base, -TmpName)
Create a name for a temporary file. Base is an identifier for the category of file. The TmpName is guaranteed to be unique. If the system halts, it will automatically remove all created temporary files. Base is used as part of the final filename. Portable applications should limit themselves to alphanumerical characters.

Because it is possible to guess the generated filename, attackers may create the filesystem entry as a link and possibly create a security issue. New code should use tmp_file_stream/3.

tmp_file_stream(+Encoding, -FileName, -Stream)
Create a temporary file name FileName and open it for writing in the given Encoding. Encoding is a text-encoding name or binary. Stream is the output stream. If the OS supports it, the created file is only accessible to the current user. If the OS supports it, the file is created using the open()-flag O_EXCL, which guarantees that the file did not exist before this call. This predicate is a safe replacement of tmp_file/2. Note that in those cases where the temporary file is needed to store output from an external command, the file must be closed first. E.g., the following downloads a file from a URL to a temporary file and opens the file for reading (On Unix systems you can delete the file after opening it for reading for cleanup):
open_url(URL, In) :-
        tmp_file_stream(text, File, Stream),
        close(Stream),
        process_create(curl, ['-o', File, URL], []),
        open(File, read, In),
        delete_file(File).              % Unix-only

Temporary files created using this call are removed if the Prolog process terminates. Calling delete_file/1 using FileName removes the file and removes the entry from the administration of files-to-be-deleted.

make_directory(+Directory)
Create a new directory (folder) on the filesystem. Raises an exception on failure. On Unix systems, the directory is created with default permissions (defined by the process umask setting).
delete_directory(+Directory)
Delete directory (folder) from the filesystem. Raises an exception on failure. Please note that in general it will not be possible to delete a non-empty directory.
working_directory(-Old, +New)
Unify Old with an absolute path to the current working directory and change working directory to New. Use the pattern working_directory(CWD, CWD) to get the current directory. See also absolute_file_name/2 and chdir/1.bugSome of the file-I/O predicates use local filenames. Changing directory while file-bound streams are open causes wrong results on telling/1, seeing/1 and current_stream/3 Note that the working directory is shared between all threads.
chdir(+Path)
Compatibility predicate. New code should use working_directory/2.