libghc-path-io-doc 1.2.2-1build6 / usr / share / doc / libghc-path-io-doc / html / path-io.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Interface to ‘directory’ package for users of ‘path’
--   
--   Interface to ‘directory’ package for users of ‘path’.
@package path-io
@version 1.2.2


-- | This module provides interface to <a>System.Directory</a> for users of
--   <a>Path</a> module. It also implements commonly used primitives like
--   recursive scanning and copying of directories.
module Path.IO

-- | <tt><a>createDir</a> dir</tt> creates a new directory <tt>dir</tt>
--   which is initially empty, or as near to empty as the operating system
--   allows.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES]</tt></li>
--   <li><tt>isAlreadyExistsError</tt> / <tt>AlreadyExists</tt> The operand
--   refers to a directory that already exists. <tt> [EEXIST]</tt></li>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><tt>NoSuchThing</tt> There is no path to the directory.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources (virtual memory,
--   process file descriptors, physical disk space, etc.) are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><tt>InappropriateType</tt> The path refers to an existing
--   non-directory object. <tt>[EEXIST]</tt></li>
--   </ul>
createDir :: MonadIO m => Path b Dir -> m ()

-- | <tt><a>createDirIfMissing</a> parents dir</tt> creates a new directory
--   <tt>dir</tt> if it doesn't exist. If the first argument is <a>True</a>
--   the function will also create all parent directories if they are
--   missing.
createDirIfMissing :: MonadIO m => Bool -> Path b Dir -> m ()

-- | Ensure that directory exists creating it and its parent directories if
--   necessary. This is just a handy shortcut:
--   
--   <pre>
--   ensureDir = createDirIfMissing True
--   </pre>
ensureDir :: MonadIO m => Path b Dir -> m ()

-- | <tt><a>removeDir</a> dir</tt> removes an existing directory
--   <tt>dir</tt>. The implementation may specify additional constraints
--   which must be satisfied before a directory can be removed (e.g. the
--   directory has to be empty, or may not be in use by other processes).
--   It is not legal for an implementation to partially remove a directory
--   unless the entire directory is removed. A conformant implementation
--   need not support directory removal in all situations (e.g. removal of
--   the root directory).
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
--   EEXIST]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   removal in this situation. <tt>[EINVAL]</tt></li>
--   <li><tt>InappropriateType</tt> The operand refers to an existing
--   non-directory object. <tt>[ENOTDIR]</tt></li>
--   </ul>
removeDir :: MonadIO m => Path b Dir -> m ()

-- | <tt><a>removeDirRecur</a> dir</tt> removes an existing directory
--   <tt>dir</tt> together with its contents and subdirectories. Within
--   this directory, symbolic links are removed without affecting their
--   targets.
removeDirRecur :: MonadIO m => Path b Dir -> m ()

-- | <tt><a>renameDir</a> old new</tt> changes the name of an existing
--   directory from <tt>old</tt> to <tt>new</tt>. If the <tt>new</tt>
--   directory already exists, it is atomically replaced by the
--   <tt>old</tt> directory. If the <tt>new</tt> directory is neither the
--   <tt>old</tt> directory nor an alias of the <tt>old</tt> directory, it
--   is removed as if by <a>removeDir</a>. A conformant implementation need
--   not support renaming directories in all situations (e.g. renaming to
--   an existing directory, or across different physical devices), but the
--   constraints must be documented.
--   
--   On Win32 platforms, <tt>renameDir</tt> fails if the <tt>new</tt>
--   directory already exists.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> Either operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
--   directory does not exist, or there is no path to the target.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
--   EEXIST]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   renaming in this situation. <tt>[EINVAL, EXDEV]</tt></li>
--   <li><tt>InappropriateType</tt> Either path refers to an existing
--   non-directory object. <tt>[ENOTDIR, EISDIR]</tt></li>
--   </ul>
renameDir :: MonadIO m => Path b0 Dir -> Path b1 Dir -> m ()

-- | <tt><a>listDir</a> dir</tt> returns a list of <i>all</i> entries in
--   <tt>dir</tt> without the special entries (<tt>.</tt> and <tt>..</tt>).
--   Entries are not sorted.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EMFILE, ENFILE]</tt></li>
--   <li><tt>InappropriateType</tt> The path refers to an existing
--   non-directory object. <tt>[ENOTDIR]</tt></li>
--   </ul>
listDir :: (MonadIO m, MonadThrow m) => Path b Dir -> m ([Path Abs Dir], [Path Abs File])

-- | Similar to <a>listDir</a>, but recursively traverses every
--   sub-directory, and collects all files and directories. This can fail
--   with the same exceptions as <a>listDir</a>.
listDirRecur :: (MonadIO m, MonadThrow m) => Path b Dir -> m ([Path Abs Dir], [Path Abs File])

-- | Copy directory recursively. This is not smart about symbolic links,
--   but tries to preserve permissions when possible. If destination
--   directory already exists, new files and sub-directories will
--   complement its structure, possibly overwriting old files if they
--   happen to have the same name as the new ones.
copyDirRecur :: (MonadIO m, MonadCatch m) => Path b0 Dir -> Path b1 Dir -> m ()

-- | The same as <a>copyDirRecur</a>, but it does not preserve directory
--   permissions. This may be useful, for example, if directory you want to
--   copy is “read-only”, but you want your copy to be editable.
copyDirRecur' :: (MonadIO m, MonadCatch m) => Path b0 Dir -> Path b1 Dir -> m ()

-- | Action returned by the traversal handler function. The action decides
--   how the traversal will proceed further.
data WalkAction

-- | Finish the entire walk altogether
WalkFinish :: WalkAction

-- | List of sub-directories to exclude from descending
WalkExclude :: [Path Abs Dir] -> WalkAction

-- | Traverse a directory tree using depth first pre-order traversal,
--   calling a handler function at each directory node traversed. The
--   absolute paths of the parent directory, sub-directories and the files
--   in the directory are provided as arguments to the handler.
--   
--   Detects and silently avoids any traversal loops in the directory tree.
walkDir :: (MonadIO m, MonadThrow m) => (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m WalkAction) -> Path b Dir -> m ()

-- | Similar to <a>walkDir</a> but accepts a <a>Monoid</a> returning,
--   output writer as well. Values returned by the output writer
--   invocations are accumulated and returned.
--   
--   Both, the descend handler as well as the output writer can be used for
--   side effects but keep in mind that the output writer runs before the
--   descend handler.
walkDirAccum :: (MonadIO m, MonadThrow m, Monoid o) => Maybe (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m WalkAction) -> (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m o) -> Path b Dir -> m o

-- | Obtain the current working directory as an absolute path.
--   
--   In a multithreaded program, the current working directory is a global
--   state shared among all threads of the process. Therefore, when
--   performing filesystem operations from multiple threads, it is highly
--   recommended to use absolute rather than relative paths (see:
--   <a>makeAbsolute</a>).
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>isDoesNotExistError</a> or <tt>NoSuchThing</tt> There is no
--   path referring to the working directory. <tt>[EPERM, ENOENT,
--   ESTALE...]</tt></li>
--   <li><tt>isPermissionError</tt> or <tt>PermissionDenied</tt> The
--   process has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation.</li>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of current working directory.</li>
--   </ul>
getCurrentDir :: (MonadIO m, MonadThrow m) => m (Path Abs Dir)

-- | Change the working directory to the given path.
--   
--   In a multithreaded program, the current working directory is a global
--   state shared among all threads of the process. Therefore, when
--   performing filesystem operations from multiple threads, it is highly
--   recommended to use absolute rather than relative paths (see:
--   <a>makeAbsolute</a>).
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> or <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> or <tt>PermissionDenied</tt> The
--   process has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of current working directory, or the working directory cannot be
--   dynamically changed.</li>
--   <li><tt>InappropriateType</tt> The path refers to an existing
--   non-directory object. <tt>[ENOTDIR]</tt></li>
--   </ul>
setCurrentDir :: MonadIO m => Path b Dir -> m ()

-- | Run an <a>IO</a> action with the given working directory and restore
--   the original working directory afterwards, even if the given action
--   fails due to an exception.
--   
--   The operation may fail with the same exceptions as
--   <a>getCurrentDir</a> and <a>setCurrentDir</a>.
withCurrentDir :: (MonadIO m, MonadMask m) => Path b Dir -> m a -> m a

-- | Returns the current user's home directory.
--   
--   The directory returned is expected to be writable by the current user,
--   but note that it isn't generally considered good practice to store
--   application-specific data here; use <a>getAppUserDataDir</a> instead.
--   
--   On Unix, <a>getHomeDir</a> returns the value of the <tt>HOME</tt>
--   environment variable. On Windows, the system is queried for a suitable
--   path; a typical path might be <tt>C:/Users/<i>&lt;user&gt;</i></tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of home directory.</li>
--   <li><a>isDoesNotExistError</a> The home directory for the current user
--   does not exist, or cannot be found.</li>
--   </ul>
getHomeDir :: (MonadIO m, MonadThrow m) => m (Path Abs Dir)

-- | Obtain the path to a special directory for storing user-specific
--   application data (traditional Unix location).
--   
--   The argument is usually the name of the application. Since it will be
--   integrated into the path, it must consist of valid path characters.
--   
--   <ul>
--   <li>On Unix-like systems, the path is
--   <tt>~/.<i>&lt;app&gt;</i></tt>.</li>
--   <li>On Windows, the path is <tt>%APPDATA%/<i>&lt;app&gt;</i></tt>
--   (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming/<i>&lt;app&gt;</i></tt>)</li>
--   </ul>
--   
--   Note: the directory may not actually exist, in which case you would
--   need to create it. It is expected that the parent directory exists and
--   is writable.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of application-specific data directory.</li>
--   <li><a>isDoesNotExistError</a> The home directory for the current user
--   does not exist, or cannot be found.</li>
--   </ul>
getAppUserDataDir :: (MonadIO m, MonadThrow m) => String -> m (Path Abs Dir)

-- | Returns the current user's document directory.
--   
--   The directory returned is expected to be writable by the current user,
--   but note that it isn't generally considered good practice to store
--   application-specific data here; use <a>getAppUserDataDir</a> instead.
--   
--   On Unix, <a>getUserDocsDir</a> returns the value of the <tt>HOME</tt>
--   environment variable. On Windows, the system is queried for a suitable
--   path; a typical path might be
--   <tt>C:/Users/<i>&lt;user&gt;</i>/Documents</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of document directory.</li>
--   <li><a>isDoesNotExistError</a> The document directory for the current
--   user does not exist, or cannot be found.</li>
--   </ul>
getUserDocsDir :: (MonadIO m, MonadThrow m) => m (Path Abs Dir)

-- | Returns the current directory for temporary files.
--   
--   On Unix, <a>getTempDir</a> returns the value of the <tt>TMPDIR</tt>
--   environment variable or "/tmp" if the variable isn't defined. On
--   Windows, the function checks for the existence of environment
--   variables in the following order and uses the first path found:
--   
--   <ul>
--   <li>TMP environment variable.</li>
--   <li>TEMP environment variable.</li>
--   <li>USERPROFILE environment variable.</li>
--   <li>The Windows directory</li>
--   </ul>
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of temporary directory.</li>
--   </ul>
--   
--   The function doesn't verify whether the path exists.
getTempDir :: (MonadIO m, MonadThrow m) => m (Path Abs Dir)

-- | Special directories for storing user-specific application data,
--   configuration, and cache files, as specified by the <a>XDG Base
--   Directory Specification</a>.
--   
--   Note: On Windows, <a>XdgData</a> and <a>XdgConfig</a> map to the same
--   directory.
data XdgDirectory :: *

-- | For data files (e.g. images). Defaults to <tt>~/.local/share</tt> and
--   can be overridden by the <tt>XDG_DATA_HOME</tt> environment variable.
--   On Windows, it is <tt>%APPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming</tt>). Can be
--   considered as the user-specific equivalent of <tt>/usr/share</tt>.
XdgData :: XdgDirectory

-- | For configuration files. Defaults to <tt>~/.config</tt> and can be
--   overridden by the <tt>XDG_CONFIG_HOME</tt> environment variable. On
--   Windows, it is <tt>%APPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming</tt>). Can be
--   considered as the user-specific equivalent of <tt>/etc</tt>.
XdgConfig :: XdgDirectory

-- | For non-essential files (e.g. cache). Defaults to <tt>~/.cache</tt>
--   and can be overridden by the <tt>XDG_CACHE_HOME</tt> environment
--   variable. On Windows, it is <tt>%LOCALAPPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Local</tt>). Can be
--   considered as the user-specific equivalent of <tt>/var/cache</tt>.
XdgCache :: XdgDirectory

-- | Obtain the paths to special directories for storing user-specific
--   application data, configuration, and cache files, conforming to the
--   <a>XDG Base Directory Specification</a>. Compared with
--   <a>getAppUserDataDir</a>, this function provides a more fine-grained
--   hierarchy as well as greater flexibility for the user.
--   
--   It also works on Windows, although in that case <tt>XdgData</tt> and
--   <tt>XdgConfig</tt> will map to the same directory.
--   
--   Note: The directory may not actually exist, in which case you would
--   need to create it with file mode <tt>700</tt> (i.e. only accessible by
--   the owner).
--   
--   Note also: this is a piece of conditional API, only available if
--   <tt>directory-1.2.3.0</tt> or later is used.
getXdgDir :: (MonadIO m, MonadThrow m) => XdgDirectory -> Maybe (Path Rel Dir) -> m (Path Abs Dir)

-- | Closed type family describing how to get absolute version of given
--   <a>Path</a>.

-- | Closed type family describing how to get relative version of given
--   <a>Path</a>.

-- | Class of things (<a>Path</a>s) that can be canonicalized and made
--   absolute.
class AnyPath path

-- | Make a path absolute and remove as many indirections from it as
--   possible. Indirections include the two special directories <tt>.</tt>
--   and <tt>..</tt>, as well as any symbolic links. The input path need
--   not point to an existing file or directory.
--   
--   <b>Note</b>: if you require only an absolute path, use
--   <a>makeAbsolute</a> instead. Most programs need not care about whether
--   a path contains symbolic links.
--   
--   Due to the fact that symbolic links and <tt>..</tt> are dependent on
--   the state of the existing filesystem, the function can only make a
--   conservative, best-effort attempt. Nevertheless, if the input path
--   points to an existing file or directory, then the output path shall
--   also point to the same file or directory.
--   
--   Formally, symbolic links and <tt>..</tt> are removed from the longest
--   prefix of the path that still points to an existing file. The function
--   is not atomic, therefore concurrent changes in the filesystem may lead
--   to incorrect results.
--   
--   (Despite the name, the function does not guarantee canonicity of the
--   returned path due to the presence of hard links, mount points, etc.)
--   
--   Similar to <tt>normalise</tt>, an empty path is equivalent to the
--   current directory.
--   
--   <i>Known bug(s)</i>: on Windows, the function does not resolve
--   symbolic links.
--   
--   Please note that before version 1.2.3.0 of <tt>directory</tt> package,
--   this function had unpredictable behavior on non-existent paths.
canonicalizePath :: (AnyPath path, MonadIO m, MonadThrow m) => path -> m (AbsPath path)

-- | Make a path absolute by prepending the current directory (if it isn't
--   already absolute) and applying <tt>normalise</tt> to the result.
--   
--   If the path is already absolute, the operation never fails. Otherwise,
--   the operation may fail with the same exceptions as
--   <tt>getCurrentDirectory</tt>.
makeAbsolute :: (AnyPath path, MonadIO m, MonadThrow m) => path -> m (AbsPath path)

-- | Make a path relative to given directory.
makeRelative :: (AnyPath path, MonadThrow m) => Path Abs Dir -> path -> m (RelPath path)

-- | Make a path relative to current working directory.
makeRelativeToCurrentDir :: (AnyPath path, MonadIO m, MonadThrow m) => path -> m (RelPath path)

-- | Append stringly-typed path to an absolute path and then canonicalize
--   it.
resolveFile :: (MonadIO m, MonadThrow m) => Path Abs Dir -> FilePath -> m (Path Abs File)

-- | The same as <a>resolveFile</a>, but uses current working directory.
resolveFile' :: (MonadIO m, MonadThrow m) => FilePath -> m (Path Abs File)

-- | The same as <a>resolveFile</a>, but for directories.
resolveDir :: (MonadIO m, MonadThrow m) => Path Abs Dir -> FilePath -> m (Path Abs Dir)

-- | The same as <a>resolveDir</a>, but uses current working directory.
resolveDir' :: (MonadIO m, MonadThrow m) => FilePath -> m (Path Abs Dir)

-- | <tt><a>removeFile</a> file</tt> removes the directory entry for an
--   existing file <tt>file</tt>, where <tt>file</tt> is not itself a
--   directory. The implementation may specify additional constraints which
--   must be satisfied before a file can be removed (e.g. the file may not
--   be in use by other processes).
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid file name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The file does
--   not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY]</tt></li>
--   <li><tt>InappropriateType</tt> The operand refers to an existing
--   directory. <tt>[EPERM, EINVAL]</tt></li>
--   </ul>
removeFile :: MonadIO m => Path b File -> m ()

-- | <tt><a>renameFile</a> old new</tt> changes the name of an existing
--   file system object from <i>old</i> to <i>new</i>. If the <i>new</i>
--   object already exists, it is atomically replaced by the <i>old</i>
--   object. Neither path may refer to an existing directory. A conformant
--   implementation need not support renaming files in all situations (e.g.
--   renaming across different physical devices), but the constraints must
--   be documented.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> Either operand is not a valid file name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
--   file does not exist, or there is no path to the target. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><tt>isPermissionError</tt> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   renaming in this situation. <tt>[EXDEV]</tt></li>
--   <li><tt>InappropriateType</tt> Either path refers to an existing
--   directory. <tt>[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]</tt></li>
--   </ul>
renameFile :: MonadIO m => Path b0 File -> Path b1 File -> m ()

-- | <tt><a>copyFile</a> old new</tt> copies the existing file from
--   <tt>old</tt> to <tt>new</tt>. If the <tt>new</tt> file already exists,
--   it is atomically replaced by the <tt>old</tt> file. Neither path may
--   refer to an existing directory. The permissions of <tt>old</tt> are
--   copied to <tt>new</tt>, if possible.
copyFile :: MonadIO m => Path b0 File -> Path b1 File -> m ()

-- | Given an executable file name, search for such file in the directories
--   listed in system <tt>PATH</tt>. The returned value is the path to the
--   found executable or <a>Nothing</a> if an executable with the given
--   name was not found. For example (<a>findExecutable</a> "ghc") gives
--   you the path to GHC.
--   
--   The path returned by <a>findExecutable</a> corresponds to the program
--   that would be executed by <a>createProcess</a> when passed the same
--   string (as a RawCommand, not a ShellCommand).
--   
--   On Windows, <a>findExecutable</a> calls the Win32 function
--   <tt>SearchPath</tt>, which may search other places before checking the
--   directories in <tt>PATH</tt>. Where it actually searches depends on
--   registry settings, but notably includes the directory containing the
--   current executable. See
--   <a>http://msdn.microsoft.com/en-us/library/aa365527.aspx</a> for more
--   details.
findExecutable :: MonadIO m => Path Rel File -> m (Maybe (Path Abs File))

-- | Search through the given set of directories for the given file.
findFile :: (MonadIO m, MonadThrow m) => [Path b Dir] -> Path Rel File -> m (Maybe (Path Abs File))

-- | Search through the given set of directories for the given file and
--   return a list of paths where the given file exists.
findFiles :: (MonadIO m, MonadThrow m) => [Path b Dir] -> Path Rel File -> m [Path Abs File]

-- | Search through the given set of directories for the given file and
--   with the given property (usually permissions) and return a list of
--   paths where the given file exists and has the property.
findFilesWith :: (MonadIO m, MonadThrow m) => (Path Abs File -> m Bool) -> [Path b Dir] -> Path Rel File -> m [Path Abs File]

-- | Use a temporary file that doesn't already exist.
--   
--   Creates a new temporary file inside the given directory, making use of
--   the template. The temporary file is deleted after use.
withTempFile :: (MonadIO m, MonadMask m) => Path b Dir -> String -> (Path Abs File -> Handle -> m a) -> m a

-- | Create and use a temporary directory.
--   
--   Creates a new temporary directory inside the given directory, making
--   use of the template. The temporary directory is deleted after use.
withTempDir :: (MonadIO m, MonadMask m) => Path b Dir -> String -> (Path Abs Dir -> m a) -> m a

-- | Create and use a temporary file in the system standard temporary
--   directory.
--   
--   Behaves exactly the same as <a>withTempFile</a>, except that the
--   parent temporary directory will be that returned by <a>getTempDir</a>.
withSystemTempFile :: (MonadIO m, MonadMask m) => String -> (Path Abs File -> Handle -> m a) -> m a

-- | Create and use a temporary directory in the system standard temporary
--   directory.
--   
--   Behaves exactly the same as <a>withTempDir</a>, except that the parent
--   temporary directory will be that returned by <a>getTempDir</a>.
withSystemTempDir :: (MonadIO m, MonadMask m) => String -> (Path Abs Dir -> m a) -> m a

-- | The function creates a temporary file in <tt>rw</tt> mode. The created
--   file isn't deleted automatically, so you need to delete it manually.
--   
--   The file is created with permissions such that only the current user
--   can read/write it.
--   
--   With some exceptions (see below), the file will be created securely in
--   the sense that an attacker should not be able to cause openTempFile to
--   overwrite another file on the filesystem using your credentials, by
--   putting symbolic links (on Unix) in the place where the temporary file
--   is to be created. On Unix the <tt>O_CREAT</tt> and <tt>O_EXCL</tt>
--   flags are used to prevent this attack, but note that <tt>O_EXCL</tt>
--   is sometimes not supported on NFS filesystems, so if you rely on this
--   behaviour it is best to use local filesystems only.
openTempFile :: (MonadIO m, MonadThrow m) => Path b Dir -> String -> m (Path Abs File, Handle)

-- | Like <a>openTempFile</a>, but opens the file in binary mode. On
--   Windows, reading a file in text mode (which is the default) will
--   translate <tt>CRLF</tt> to <tt>LF</tt>, and writing will translate
--   <tt>LF</tt> to <tt>CRLF</tt>. This is usually what you want with text
--   files. With binary files this is undesirable; also, as usual under
--   Microsoft operating systems, text mode treats control-Z as EOF. Binary
--   mode turns off all special treatment of end-of-line and end-of-file
--   characters.
openBinaryTempFile :: (MonadIO m, MonadThrow m) => Path b Dir -> String -> m (Path Abs File, Handle)

-- | Create temporary directory. The created directory isn't deleted
--   automatically, so you need to delete it manually.
--   
--   The directory is created with permissions such that only the current
--   user can read/write it.
createTempDir :: (MonadIO m, MonadThrow m) => Path b Dir -> String -> m (Path Abs Dir)

-- | The operation <a>doesFileExist</a> returns <a>True</a> if the argument
--   file exists and is not a directory, and <a>False</a> otherwise.
doesFileExist :: MonadIO m => Path b File -> m Bool

-- | The operation <a>doesDirExist</a> returns <a>True</a> if the argument
--   file exists and is either a directory or a symbolic link to a
--   directory, and <a>False</a> otherwise.
doesDirExist :: MonadIO m => Path b Dir -> m Bool

-- | Check if there is a file or directory on specified path.
isLocationOccupied :: MonadIO m => Path b t -> m Bool

-- | If argument of the function throws a <a>doesNotExistErrorType</a>,
--   <a>Nothing</a> is returned (other exceptions propagate). Otherwise the
--   result is returned inside a <a>Just</a>.
forgivingAbsence :: (MonadIO m, MonadCatch m) => m a -> m (Maybe a)

-- | The same as <a>forgivingAbsence</a>, but ignores result.
ignoringAbsence :: (MonadIO m, MonadCatch m) => m a -> m ()
data Permissions :: *
emptyPermissions :: Permissions
readable :: Permissions -> Bool
writable :: Permissions -> Bool
executable :: Permissions -> Bool
searchable :: Permissions -> Bool
setOwnerReadable :: Bool -> Permissions -> Permissions
setOwnerWritable :: Bool -> Permissions -> Permissions
setOwnerExecutable :: Bool -> Permissions -> Permissions
setOwnerSearchable :: Bool -> Permissions -> Permissions

-- | The <a>getPermissions</a> operation returns the permissions for the
--   file or directory.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to access
--   the permissions; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
getPermissions :: MonadIO m => Path b t -> m Permissions

-- | The <a>setPermissions</a> operation sets the permissions for the file
--   or directory.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to set the
--   permissions; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
setPermissions :: MonadIO m => Path b t -> Permissions -> m ()

-- | Set permissions for the object found on second given path so they
--   match permissions of the object on the first path.
copyPermissions :: MonadIO m => Path b0 t0 -> Path b1 t1 -> m ()

-- | Obtain the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to read
--   the access time; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
--   
--   Caveat for POSIX systems: This function returns a timestamp with
--   sub-second resolution only if this package is compiled against
--   <tt>unix-2.6.0.0</tt> or later and the underlying filesystem supports
--   them.
--   
--   Note: this is a piece of conditional API, only available if
--   <tt>directory-1.2.3.0</tt> or later is used.
getAccessTime :: MonadIO m => Path b t -> m UTCTime

-- | Change the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to alter
--   the access time; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
--   
--   Some caveats for POSIX systems:
--   
--   <ul>
--   <li>Not all systems support <tt>utimensat</tt>, in which case the
--   function can only emulate the behavior by reading the modification
--   time and then setting both the access and modification times together.
--   On systems where <tt>utimensat</tt> is supported, the access time is
--   set atomically with nanosecond precision.</li>
--   <li>If compiled against a version of <tt>unix</tt> prior to
--   <tt>2.7.0.0</tt>, the function would not be able to set timestamps
--   with sub-second resolution. In this case, there would also be loss of
--   precision in the modification time.</li>
--   </ul>
--   
--   Note: this is a piece of conditional API, only available if
--   <tt>directory-1.2.3.0</tt> or later is used.
setAccessTime :: MonadIO m => Path b t -> UTCTime -> m ()

-- | Change the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to alter
--   the modification time; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
--   
--   Some caveats for POSIX systems:
--   
--   <ul>
--   <li>Not all systems support <tt>utimensat</tt>, in which case the
--   function can only emulate the behavior by reading the access time and
--   then setting both the access and modification times together. On
--   systems where <tt>utimensat</tt> is supported, the modification time
--   is set atomically with nanosecond precision.</li>
--   <li>If compiled against a version of <tt>unix</tt> prior to
--   <tt>2.7.0.0</tt>, the function would not be able to set timestamps
--   with sub-second resolution. In this case, there would also be loss of
--   precision in the access time.</li>
--   </ul>
--   
--   Note: this is a piece of conditional API, only available if
--   <tt>directory-1.2.3.0</tt> or later is used.
setModificationTime :: MonadIO m => Path b t -> UTCTime -> m ()

-- | Obtain the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>isPermissionError</tt> if the user is not permitted to read
--   the modification time; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
--   
--   Caveat for POSIX systems: This function returns a timestamp with
--   sub-second resolution only if this package is compiled against
--   <tt>unix-2.6.0.0</tt> or later and the underlying filesystem supports
--   them.
getModificationTime :: MonadIO m => Path b t -> m UTCTime
instance Path.IO.AnyPath (Path.Internal.Path b Path.File)
instance Path.IO.AnyPath (Path.Internal.Path b Path.Dir)