% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(filesex): Extended operations on files}

\label{sec:filesex}

This module provides additional operations on files. This covers both
more obscure and possible non-portable low-level operations and
high-level utilities.

Using these Prolog primitives is typically to be preferred over using
operating system primitives through \predref{shell}{1} or \predref{process_create}{3} because
(1) there are no potential file name quoting issues, (2) there is no
dependency on operating system commands and (3) using the
implementations from this library is usually faster.\vspace{0.7cm}

\begin{description}
    \predicate[det]{set_time_file}{3}{+File, -OldTimes, +NewTimes}
Query and set POSIX time attributes of a file. Both \arg{OldTimes} and
\arg{NewTimes} are lists of option-terms. Times are represented in
SWI-Prolog's standard floating point numbers. New times may be
specified as \const{now} to indicate the current time. Defined options
are:

\begin{description}
    \termitem{access}{Time}
Describes the time of last access of the file. This value
can be read and written.
    \termitem{modified}{Time}
Describes the time the contents of the file was last
modified. This value can be read and written.
    \termitem{changed}{Time}
Describes the time the file-structure itself was changed by
adding (\verb$link()$) or removing (\verb$unlink()$) names.
\end{description}

Below are some example queries. The first retrieves the
access-time, while the second sets the last-modified time to the
current time.

\begin{code}
?- set_time_file(foo, [access(Access)], []).
?- set_time_file(foo, [], [modified(now)]).
\end{code}

    \predicate[det]{link_file}{3}{+OldPath, +NewPath, +Type}
Create a link in the filesystem from \arg{NewPath} to \arg{OldPath}. \arg{Type}
defines the type of link and is one of \const{hard} or \const{symbolic}.

With some limitations, these functions also work on Windows. First
of all, the underlying filesystem must support links. This requires
NTFS. Second, symbolic links are only supported in Vista and later.

\begin{tags}
    \tag{Errors}
\verb$domain_error(link_type, Type)$ if the requested link-type
is unknown or not supported on the target OS.
\end{tags}

    \predicate[det]{relative_file_name}{3}{+Path:atom, +RelToFile:atom, -RelPath:atom}
\nodescription
    \predicate[det]{relative_file_name}{3}{-Path:atom, +RelToFile:atom, +RelPath:atom}
True when \arg{RelPath} is \arg{Path}, relative to the \textit{file} \arg{RelToFile}. \arg{Path} and
RelTo are first handed to \predref{absolute_file_name}{2}, which makes the
absolute \textbf{and} canonical. Below are two examples:

\begin{code}
?- relative_file_name('/home/janw/nice',
                      '/home/janw/deep/dir/file', Path).
Path = '../../nice'.

?- relative_file_name(Path, '/home/janw/deep/dir/file', '../../nice').
Path = '/home/janw/nice'.
\end{code}

Add a terminating \verb$/$ to get a path relative to a \textit{directory}, e.g.

\begin{code}
?- relative_file_name('/home/janw/deep/dir/file', './', Path).
Path = 'deep/dir/file'.
\end{code}

\begin{arguments}
\arg{All} & paths must be in canonical POSIX notation, i.e.,
using / to separate segments in the path. See
\predref{prolog_to_os_filename}{2}. \\
\end{arguments}

\begin{tags}
    \tag{bug}
It would probably have been cleaner to use a directory
as second argument. We can not do such dynamically as this
predicate is defined as a \textit{syntactical} operation, which
implies it may be used for non-existing paths and URLs.
\end{tags}

    \predicate[det]{directory_file_path}{3}{+Directory, +File, -Path}
\nodescription
    \predicate[det]{directory_file_path}{3}{?Directory, ?File, +Path}
True when \arg{Path} is the full path-name for \arg{File} in Dir. This is
comparable to \verb$atom_concat(Directory, File, Path)$, but it ensures
there is exactly one / between the two parts. Notes:

\begin{itemize}
    \item In mode (+,+,-), if \arg{File} is given and absolute, \arg{Path}
is unified to \arg{File}.
    \item Mode (-,-,+) uses \predref{file_directory_name}{2} and \predref{file_base_name}{2}
\end{itemize}

    \predicate[nondet]{directory_member}{3}{+Directory, -Member, +Options}
True when \arg{Member} is a path inside \arg{Directory}. \arg{Options} defined are:

\begin{description}
    \termitem{recursive}{+Boolean}
If \const{true} (default \const{false}), recurse into subdirectories
    \termitem{follow_links}{+Boolean}
If \const{true} (default), follow symbolic links.
    \termitem{file_type}{+Type}
See \predref{absolute_file_name}{3}.
    \termitem{extensions}{+List}
Only return entries whose extension appears in \arg{List}.
    \termitem{file_errors}{+Errors}
How to handle errors. One of \const{fail}, \const{warning} or \const{error}.
Default is \const{warning}. \arg{Errors} notably happen if a directory is
unreadable or a link points nowhere.
    \termitem{access}{+Access}
Only return entries with \arg{Access}
    \termitem{matches}{+GlobPattern}
Only return files that match \arg{GlobPattern}.
    \termitem{exclude}{+GlobPattern}
Exclude files matching \arg{GlobPattern}.
    \termitem{exclude_directory}{+GlobPattern}
Do not recurse into directories matching \arg{GlobPattern}.
    \termitem{hidden}{+Boolean}
If \const{true} (default), also return \textit{hidden} files.
\end{description}

This predicate is safe against cycles introduced by symbolic links
to directories.

The idea for a non-deterministic file search predicate comes from
Nicos Angelopoulos.

    \predicate[det]{copy_file}{2}{+From, +To}
Copy a file into a new file or directory. The data is copied as
binary data.

    \predicate[det]{make_directory_path}{1}{+Dir}
Create \arg{Dir} and all required components (like mkdir -p). Can
raise various file-specific exceptions.

    \predicate[det]{copy_directory}{2}{+From, +To}
Copy the contents of the directory \arg{From} to \arg{To} (recursively). If
\arg{To} is the name of an existing directory, the \textit{contents} of \arg{From}
are copied into \arg{To}. I.e., no subdirectory using the basename of
\arg{From} is created.

    \predicate[det]{delete_directory_and_contents}{1}{+Dir}
Recursively remove the directory \arg{Dir} and its contents. If \arg{Dir} is
a symbolic link or symbolic links inside \arg{Dir} are encountered,
the links are removed rather than their content. Use with care!

    \predicate[det]{delete_directory_contents}{1}{+Dir}
Remove all content from directory \arg{Dir}, without removing \arg{Dir}
itself. Similar to \predref{delete_directory_and_contents}{2}, if symbolic
links are encountered in \arg{Dir}, the links are removed rather than
their content.

    \predicate[det]{chmod}{2}{+File, +Spec}
Set the mode of the target file. \arg{Spec} is one of \verb$+Mode$, \verb$-Mode$ or
a plain \arg{Mode}, which adds new permissions, revokes permissions or
sets the exact permissions. \arg{Mode} itself is an integer, a POSIX
mode name or a list of POSIX mode names. Defines names are \const{suid},
\const{sgid}, \const{svtx} and all names defined by the regular expression
\verb$[ugo]*[rwx]*$. Specifying none of "ugo" is the same as specifying
all of them. For example, to make a file executable for the owner
(user) and group, we can use:

\begin{code}
?- chmod(myfile, +ugx).
\end{code}

\end{description}