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


-- | Platform-agnostic library for filesystem operations
--   
--   This library provides a basic set of operations for manipulating files
--   and directories in a portable way.
@package directory
@version 1.3.8.3


-- | Internal modules are always subject to change from version to version.
--   The contents of this module are also platform-dependent, hence what is
--   shown in the Hackage documentation may differ from what is actually
--   available on your system.
module System.Directory.Internal
data FileType
File :: FileType

-- | POSIX: either file or directory link; Windows: file link
SymbolicLink :: FileType
Directory :: FileType

-- | Windows only: directory link
DirectoryLink :: FileType

-- | Fallibly converts String to OsString. Only intended to be used on
--   literals.
os :: String -> OsString

-- | Newtype representing short operating system specific strings.
--   
--   Internally this is either <a>WindowsString</a> or <a>PosixString</a>,
--   depending on the platform. Both use unpinned <tt>ShortByteString</tt>
--   for efficiency.
--   
--   The constructor is only exported via
--   <a>System.OsString.Internal.Types</a>, since dealing with the
--   internals isn't generally recommended, but supported in case you need
--   to write platform specific code.
data OsString

-- | Type representing filenames/pathnames.
--   
--   This type doesn't add any guarantees over <a>OsString</a>.
type OsPath = OsString

-- | 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> usually map to
--   the same directory.
data XdgDirectory

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.local/share</tt>. On Windows, the default 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. It uses the <tt>XDG_CONFIG_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.config</tt>. On Windows, the default 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). It uses the
--   <tt>XDG_CACHE_HOME</tt> environment variable. On non-Windows systems,
--   the default is <tt>~/.cache</tt>. On Windows, the default 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

-- | For data that should persist between (application) restarts, but that
--   is not important or portable enough to the user that it should be
--   stored in <a>XdgData</a>. It uses the <tt>XDG_STATE_HOME</tt>
--   environment variable. On non-Windows sytems, the default is
--   <tt>~/.local/state</tt>. On Windows, the default is
--   <tt>%LOCALAPPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Local</tt>).
XdgState :: XdgDirectory

-- | Search paths for various application data, as specified by the <a>XDG
--   Base Directory Specification</a>.
--   
--   The list of paths is split using <a>searchPathSeparator</a>, which on
--   Windows is a semicolon.
--   
--   Note: On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> usually
--   yield the same result.
data XdgDirectoryList

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/usr/local/share/</tt> and <tt>/usr/share/</tt>. On Windows, the
--   default is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt> (e.g.
--   <tt>C:/ProgramData</tt>).
XdgDataDirs :: XdgDirectoryList

-- | For configuration files. It uses the <tt>XDG_CONFIG_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/etc/xdg</tt>. On Windows, the default is <tt>%PROGRAMDATA%</tt>
--   or <tt>%ALLUSERSPROFILE%</tt> (e.g. <tt>C:/ProgramData</tt>).
XdgConfigDirs :: XdgDirectoryList
data Permissions
Permissions :: Bool -> Bool -> Bool -> Bool -> Permissions
[readable] :: Permissions -> Bool
[writable] :: Permissions -> Bool
[executable] :: Permissions -> Bool
[searchable] :: Permissions -> Bool

-- | A generator with side-effects.
newtype ListT (m :: Type -> Type) a
ListT :: m (Maybe (a, ListT m a)) -> ListT (m :: Type -> Type) a
[unListT] :: ListT (m :: Type -> Type) a -> m (Maybe (a, ListT m a))
emptyListT :: forall (m :: Type -> Type) a. Applicative m => ListT m a
maybeToListT :: Applicative m => m (Maybe a) -> ListT m a
listToListT :: forall (m :: Type -> Type) a. Applicative m => [a] -> ListT m a
liftJoinListT :: Monad m => m (ListT m a) -> ListT m a
listTHead :: Functor m => ListT m a -> m (Maybe a)
listTToList :: Monad m => ListT m a -> m [a]
andM :: Monad m => m Bool -> m Bool -> m Bool
sequenceWithIOErrors_ :: [IO ()] -> IO ()

-- | Similar to <a>try</a> but only catches a specify kind of
--   <a>IOError</a> as specified by the predicate.
tryIOErrorType :: (IOError -> Bool) -> IO a -> IO (Either IOError a)

-- | Attempt to perform the given action, silencing any IO exception thrown
--   by it.
ignoreIOExceptions :: IO () -> IO ()
specializeErrorString :: String -> (IOError -> Bool) -> IO a -> IO a
ioeAddLocation :: IOError -> String -> IOError
rightOrError :: Exception e => Either e a -> a

-- | Fallibly converts OsString to String. Only intended to be used on
--   literals.
so :: OsString -> String
ioeSetOsPath :: IOError -> OsPath -> IOError

-- | Given a list of path segments, expand <tt>.</tt> and <tt>..</tt>. The
--   path segments must not contain path separators.
expandDots :: [OsPath] -> [OsPath]

-- | Convert to the right kind of slashes.
normalisePathSeps :: OsPath -> OsPath

-- | Remove redundant trailing slashes and pick the right kind of slash.
normaliseTrailingSep :: OsPath -> OsPath

-- | Convert empty paths to the current directory, otherwise leave it
--   unchanged.
emptyToCurDir :: OsPath -> OsPath

-- | Similar to <a>normalise</a> but empty paths stay empty.
simplifyPosix :: OsPath -> OsPath

-- | Similar to <a>normalise</a> but:
--   
--   <ul>
--   <li>empty paths stay empty,</li>
--   <li>parent dirs (<tt>..</tt>) are expanded, and</li>
--   <li>paths starting with <tt>\\?\</tt> are preserved.</li>
--   </ul>
--   
--   The goal is to preserve the meaning of paths better than
--   <a>normalise</a>.
simplifyWindows :: OsPath -> OsPath

-- | Check whether the given <a>FileType</a> is considered a directory by
--   the operating system. This affects the choice of certain functions
--   e.g. <a>removeDirectory</a> vs <a>removeFile</a>.
fileTypeIsDirectory :: FileType -> Bool

-- | Return whether the given <a>FileType</a> is a link.
fileTypeIsLink :: FileType -> Bool
withBinaryHandle :: IO Handle -> (Handle -> IO r) -> IO r

-- | Copy data from one handle to another until end of file.
copyHandleData :: Handle -> Handle -> IO ()
setFileMode :: OsPath -> Mode -> IO ()
createSymbolicLink :: Bool -> OsPath -> OsPath -> IO ()
readSymbolicLink :: OsPath -> IO OsPath
createDirectoryInternal :: OsPath -> IO ()
removePathInternal :: Bool -> OsPath -> IO ()
renamePathInternal :: OsPath -> OsPath -> IO ()
filesAlwaysRemovable :: Bool

-- | On POSIX, equivalent to <a>simplifyPosix</a>.
simplify :: OsPath -> OsPath
c_free :: Ptr a -> IO ()
c_PATH_MAX :: Maybe Int
c_realpath :: CString -> CString -> IO CString
withRealpath :: CString -> (CString -> IO a) -> IO a
realPath :: OsPath -> IO OsPath
canonicalizePathSimplify :: OsPath -> IO OsPath
findExecutablesLazyInternal :: ([OsPath] -> OsString -> ListT IO OsPath) -> OsString -> ListT IO OsPath

-- | Get the contents of the <tt>PATH</tt> environment variable.
getPath :: IO [OsPath]
exeExtensionInternal :: OsString
getDirectoryContentsInternal :: OsPath -> IO [OsPath]
getCurrentDirectoryInternal :: IO OsPath

-- | Convert a path into an absolute path. If the given path is relative,
--   the current directory is prepended and the path may or may not be
--   simplified. If the path is already absolute, the path is returned
--   unchanged. The function preserves the presence or absence of the
--   trailing path separator.
--   
--   If the path is already absolute, the operation never fails. Otherwise,
--   the operation may throw exceptions.
--   
--   Empty paths are treated as the current directory.
prependCurrentDirectory :: OsPath -> IO OsPath
setCurrentDirectoryInternal :: OsPath -> IO ()
linkToDirectoryIsDirectory :: Bool
createHardLink :: OsPath -> OsPath -> IO ()
type Metadata = FileStatus
getSymbolicLinkMetadata :: OsPath -> IO Metadata
getFileMetadata :: OsPath -> IO Metadata
fileTypeFromMetadata :: Metadata -> FileType
fileSizeFromMetadata :: Metadata -> Integer
accessTimeFromMetadata :: Metadata -> UTCTime
modificationTimeFromMetadata :: Metadata -> UTCTime
type Mode = FileMode
modeFromMetadata :: Metadata -> Mode
allWriteMode :: FileMode
hasWriteMode :: Mode -> Bool
setWriteMode :: Bool -> Mode -> Mode
setFilePermissions :: OsPath -> Mode -> IO ()
getAccessPermissions :: OsPath -> IO Permissions
setAccessPermissions :: OsPath -> Permissions -> IO ()
copyOwnerFromStatus :: FileStatus -> OsPath -> IO ()
copyGroupFromStatus :: FileStatus -> OsPath -> IO ()
tryCopyOwnerAndGroupFromStatus :: FileStatus -> OsPath -> IO ()
defaultFlags :: OpenFileFlags
openFileForRead :: OsPath -> IO Handle
openFileForWrite :: OsPath -> IO Handle

-- | Truncate the destination file and then copy the contents of the source
--   file to the destination file. If the destination file already exists,
--   its attributes shall remain unchanged. Otherwise, its attributes are
--   reset to the defaults.
copyFileContents :: OsPath -> OsPath -> IO ()
copyFileWithMetadataInternal :: (Metadata -> OsPath -> IO ()) -> (Metadata -> OsPath -> IO ()) -> OsPath -> OsPath -> IO ()
setTimes :: OsPath -> (Maybe POSIXTime, Maybe POSIXTime) -> IO ()
lookupEnvOs :: OsString -> IO (Maybe OsString)
getEnvOs :: OsString -> IO OsString

-- | $HOME is preferred, because the user has control over it. However,
--   POSIX doesn't define it as a mandatory variable, so fall back to
--   <tt>getpwuid_r</tt>.
getHomeDirectoryInternal :: IO OsPath
getXdgDirectoryFallback :: IO OsPath -> XdgDirectory -> IO OsPath
getXdgDirectoryListFallback :: XdgDirectoryList -> IO [OsPath]
getAppUserDataDirectoryInternal :: OsPath -> IO OsPath
getUserDocumentsDirectoryInternal :: IO OsPath
getTemporaryDirectoryInternal :: IO OsPath


-- | System-independent interface to directory manipulation.
module System.Directory.OsPath

-- | <tt><a>createDirectory</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><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES]</tt></li>
--   <li><a>isAlreadyExistsError</a> 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><a>isDoesNotExistError</a> There is no path to the directory.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isFullError</a> 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>
createDirectory :: OsPath -> IO ()

-- | <tt><a>createDirectoryIfMissing</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.
createDirectoryIfMissing :: Bool -> OsPath -> IO ()

-- | <tt><a>removeDirectory</a> dir</tt> removes an existing directory
--   <i>dir</i>. 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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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>
removeDirectory :: OsPath -> IO ()

-- | <tt><a>removeDirectoryRecursive</a> dir</tt> removes an existing
--   directory <i>dir</i> together with its contents and subdirectories.
--   Within this directory, symbolic links are removed without affecting
--   their targets.
--   
--   On Windows, the operation fails if <i>dir</i> is a directory symbolic
--   link.
--   
--   This operation is reported to be flaky on Windows so retry logic may
--   be advisable. See:
--   <a>https://github.com/haskell/directory/pull/108</a>
removeDirectoryRecursive :: OsPath -> IO ()

-- | Removes a file or directory at <i>path</i> together with its contents
--   and subdirectories. Symbolic links are removed without affecting their
--   targets. If the path does not exist, nothing happens.
--   
--   Unlike other removal functions, this function will also attempt to
--   delete files marked as read-only or otherwise made unremovable due to
--   permissions. As a result, if the removal is incomplete, the
--   permissions or attributes on the remaining files may be altered. If
--   there are hard links in the directory, then permissions on all related
--   hard links may be altered.
--   
--   If an entry within the directory vanishes while
--   <tt>removePathForcibly</tt> is running, it is silently ignored.
--   
--   If an exception occurs while removing an entry,
--   <tt>removePathForcibly</tt> will still try to remove as many entries
--   as it can before failing with an exception. The first exception that
--   it encountered is re-thrown.
removePathForcibly :: OsPath -> IO ()

-- | <tt><a>renameDirectory</a> old new</tt> changes the name of an
--   existing directory from <i>old</i> to <i>new</i>. If the <i>new</i>
--   directory already exists, it is atomically replaced by the <i>old</i>
--   directory. If the <i>new</i> directory is neither the <i>old</i>
--   directory nor an alias of the <i>old</i> directory, it is removed as
--   if by <a>removeDirectory</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>renameDirectory</tt> fails if the <i>new</i>
--   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> The original directory does not exist,
--   or there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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>
renameDirectory :: OsPath -> OsPath -> IO ()

-- | <tt><a>listDirectory</a> dir</tt> returns a list of <i>all</i> entries
--   in <i>dir</i> without the special entries (<tt>.</tt> and
--   <tt>..</tt>).
--   
--   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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EACCES]</tt></li>
--   <li><a>isFullError</a> 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>
listDirectory :: OsPath -> IO [OsPath]

-- | Similar to <a>listDirectory</a>, but always includes the special
--   entries (<tt>.</tt> and <tt>..</tt>). (This applies to Windows as
--   well.)
--   
--   The operation may fail with the same exceptions as
--   <a>listDirectory</a>.
getDirectoryContents :: OsPath -> IO [OsPath]

-- | 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>).
--   
--   Note that <a>getCurrentDirectory</a> is not guaranteed to return the
--   same path received by <a>setCurrentDirectory</a>. On POSIX systems,
--   the path returned will always be fully dereferenced (not contain any
--   symbolic links). For more information, refer to the documentation of
--   <a>getcwd</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> There is no path referring to the
--   working directory. <tt>[EPERM, ENOENT, ESTALE...]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EACCES]</tt></li>
--   <li><a>isFullError</a> 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>
getCurrentDirectory :: IO OsPath

-- | 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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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>
setCurrentDirectory :: OsPath -> IO ()

-- | 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>getCurrentDirectory</a> and <a>setCurrentDirectory</a>.
withCurrentDirectory :: OsPath -> IO a -> IO 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>getXdgDirectory</a> or
--   <a>getAppUserDataDirectory</a> instead.
--   
--   On Unix, <a>getHomeDirectory</a> behaves as follows:
--   
--   <ul>
--   <li>Returns $HOME env variable if set (including to an empty
--   string).</li>
--   <li>Otherwise uses home directory returned by <tt>getpwuid_r</tt>
--   using the UID of the current proccesses user. This basically reads the
--   <i>etc</i>passwd file. An empty home directory field is considered
--   valid.</li>
--   </ul>
--   
--   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>
getHomeDirectory :: IO OsPath

-- | 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> usually map to
--   the same directory.
data XdgDirectory

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.local/share</tt>. On Windows, the default 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. It uses the <tt>XDG_CONFIG_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.config</tt>. On Windows, the default 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). It uses the
--   <tt>XDG_CACHE_HOME</tt> environment variable. On non-Windows systems,
--   the default is <tt>~/.cache</tt>. On Windows, the default 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

-- | For data that should persist between (application) restarts, but that
--   is not important or portable enough to the user that it should be
--   stored in <a>XdgData</a>. It uses the <tt>XDG_STATE_HOME</tt>
--   environment variable. On non-Windows sytems, the default is
--   <tt>~/.local/state</tt>. On Windows, the default is
--   <tt>%LOCALAPPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Local</tt>).
XdgState :: 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>getAppUserDataDirectory</a>, this function provides a more
--   fine-grained hierarchy as well as greater flexibility for the user.
--   
--   On Windows, <a>XdgData</a> and <a>XdgConfig</a> usually map to the
--   same directory unless overridden.
--   
--   Refer to the docs of <a>XdgDirectory</a> for more details.
--   
--   The second argument is usually the name of the application. Since it
--   will be integrated into the path, it must consist of valid path
--   characters. Note: if the second argument is an absolute path, it will
--   just return the second argument.
--   
--   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).
--   
--   As of 1.3.5.0, the environment variable is ignored if set to a
--   relative path, per revised XDG Base Directory Specification. See
--   <a>#100</a>.
getXdgDirectory :: XdgDirectory -> OsPath -> IO OsPath

-- | Search paths for various application data, as specified by the <a>XDG
--   Base Directory Specification</a>.
--   
--   The list of paths is split using <a>searchPathSeparator</a>, which on
--   Windows is a semicolon.
--   
--   Note: On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> usually
--   yield the same result.
data XdgDirectoryList

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/usr/local/share/</tt> and <tt>/usr/share/</tt>. On Windows, the
--   default is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt> (e.g.
--   <tt>C:/ProgramData</tt>).
XdgDataDirs :: XdgDirectoryList

-- | For configuration files. It uses the <tt>XDG_CONFIG_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/etc/xdg</tt>. On Windows, the default is <tt>%PROGRAMDATA%</tt>
--   or <tt>%ALLUSERSPROFILE%</tt> (e.g. <tt>C:/ProgramData</tt>).
XdgConfigDirs :: XdgDirectoryList

-- | Similar to <a>getXdgDirectory</a> but retrieves the entire list of XDG
--   directories.
--   
--   On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> usually map to
--   the same list of directories unless overridden.
--   
--   Refer to the docs of <a>XdgDirectoryList</a> for more details.
getXdgDirectoryList :: XdgDirectoryList -> IO [OsPath]

-- | Obtain the path to a special directory for storing user-specific
--   application data (traditional Unix location). Newer applications may
--   prefer the the XDG-conformant location provided by
--   <a>getXdgDirectory</a> (<a>migration guide</a>).
--   
--   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>
getAppUserDataDirectory :: OsPath -> IO OsPath

-- | 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>getXdgDirectory</a> or
--   <a>getAppUserDataDirectory</a> instead.
--   
--   On Unix, <a>getUserDocumentsDirectory</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>
getUserDocumentsDirectory :: IO OsPath

-- | Returns the current directory for temporary files.
--   
--   On Unix, <a>getTemporaryDirectory</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.
getTemporaryDirectory :: IO OsPath

-- | <a>removeFile</a> <i>file</i> removes the directory entry for an
--   existing file <i>file</i>, where <i>file</i> 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> The file does not exist. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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 :: OsPath -> IO ()

-- | <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 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. On Windows, this does not support
--   renaming across different physical devices; if you are looking to do
--   so, consider using <a>copyFileWithMetadata</a> and <a>removeFile</a>.
--   
--   On Windows, this calls <tt>MoveFileEx</tt> with
--   <tt>MOVEFILE_REPLACE_EXISTING</tt> set, which is not guaranteed to be
--   atomic (<a>https://github.com/haskell/directory/issues/109</a>).
--   
--   On other platforms, this operation is atomic.
--   
--   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> The original file does not exist, or
--   there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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 :: OsPath -> OsPath -> IO ()

-- | Rename a file or directory. If the destination path already exists, it
--   is replaced atomically. The destination path must not point 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> The original file does not exist, or
--   there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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 the destination path refers to
--   an existing directory, or one of the parent segments in the
--   destination path is not a directory. <tt>[ENOTDIR, EISDIR, EINVAL,
--   EEXIST, ENOTEMPTY]</tt></li>
--   </ul>
renamePath :: OsPath -> OsPath -> IO ()

-- | Copy a file with its permissions. If the destination file already
--   exists, it is replaced atomically. Neither path may refer to an
--   existing directory. No exceptions are thrown if the permissions could
--   not be copied.
copyFile :: OsPath -> OsPath -> IO ()

-- | Copy a file with its associated metadata. If the destination file
--   already exists, it is overwritten. There is no guarantee of atomicity
--   in the replacement of the destination file. Neither path may refer to
--   an existing directory. If the source and/or destination are symbolic
--   links, the copy is performed on the targets of the links.
--   
--   On Windows, it behaves like the Win32 function <a>CopyFile</a>, which
--   copies various kinds of metadata including file attributes and
--   security resource properties.
--   
--   On Unix-like systems, permissions, access time, and modification time
--   are preserved. If possible, the owner and group are also preserved.
--   Note that the very act of copying can change the access time of the
--   source file, hence the access times of the two files may differ after
--   the operation completes.
copyFileWithMetadata :: OsPath -> OsPath -> IO ()

-- | Obtain the size of a file in bytes.
getFileSize :: OsPath -> IO Integer

-- | Make a path absolute, normalize the path, and remove as many
--   indirections from it as possible. Any trailing path separators are
--   discarded via <a>dropTrailingPathSeparator</a>. Additionally, on
--   Windows the letter case of the path is canonicalized.
--   
--   <b>Note</b>: This function is a very big hammer. If you only need an
--   absolute path, <a>makeAbsolute</a> is sufficient for removing
--   dependence on the current working directory.
--   
--   Indirections include the two special directories <tt>.</tt> and
--   <tt>..</tt>, as well as any symbolic links (and junction points on
--   Windows). The input path need not point to an existing file or
--   directory. Canonicalization is performed on the longest prefix of the
--   path that points to an existing file or directory. The remaining
--   portion of the path that does not point to an existing file or
--   directory will still be normalized, but case canonicalization and
--   indirection removal are skipped as they are impossible to do on a
--   nonexistent path.
--   
--   Most programs should not worry about the canonicity of a path. In
--   particular, despite the name, the function does not truly guarantee
--   canonicity of the returned path due to the presence of hard links,
--   mount points, etc.
--   
--   If the path points to an existing file or directory, then the output
--   path shall also point to the same file or directory, subject to the
--   condition that the relevant parts of the file system do not change
--   while the function is still running. In other words, the function is
--   definitively not atomic. The results can be utterly wrong if the
--   portions of the path change while this function is running.
--   
--   Since some indirections (symbolic links on all systems, <tt>..</tt> on
--   non-Windows systems, and junction points on Windows) are dependent on
--   the state of the existing filesystem, the function can only make a
--   conservative attempt by removing such indirections from the longest
--   prefix of the path that still points to an existing file or directory.
--   
--   Note that on Windows parent directories <tt>..</tt> are always fully
--   expanded before the symbolic links, as consistent with the rest of the
--   Windows API (such as <tt>GetFullPathName</tt>). In contrast, on POSIX
--   systems parent directories <tt>..</tt> are expanded alongside symbolic
--   links from left to right. To put this more concretely: if <tt>L</tt>
--   is a symbolic link for <tt>R/P</tt>, then on Windows <tt>L\..</tt>
--   refers to <tt>.</tt>, whereas on other operating systems <tt>L/..</tt>
--   refers to <tt>R</tt>.
--   
--   Similar to <a>normalise</a>, passing an empty path is equivalent to
--   passing the current directory.
--   
--   <tt>canonicalizePath</tt> can resolve at least 64 indirections in a
--   single path, more than what is supported by most operating systems.
--   Therefore, it may return the fully resolved path even though the
--   operating system itself would have long given up.
--   
--   On Windows XP or earlier systems, junction expansion is not performed
--   due to their lack of <tt>GetFinalPathNameByHandle</tt>.
--   
--   <i>Changes since 1.2.3.0:</i> The function has been altered to be more
--   robust and has the same exception behavior as <a>makeAbsolute</a>.
--   
--   <i>Changes since 1.3.0.0:</i> The function no longer preserves the
--   trailing path separator. File symbolic links that appear in the middle
--   of a path are properly dereferenced. Case canonicalization and
--   symbolic link expansion are now performed on Windows.
canonicalizePath :: OsPath -> IO OsPath

-- | Convert a path into an absolute path. If the given path is relative,
--   the current directory is prepended and then the combined result is
--   normalized. If the path is already absolute, the path is simply
--   normalized. The function preserves the presence or absence of the
--   trailing path separator unless the path refers to the root directory
--   <tt>/</tt>.
--   
--   If the path is already absolute, the operation never fails. Otherwise,
--   the operation may fail with the same exceptions as
--   <a>getCurrentDirectory</a>.
makeAbsolute :: OsPath -> IO OsPath

-- | Construct a path relative to the current directory, similar to
--   <a>makeRelative</a>.
--   
--   The operation may fail with the same exceptions as
--   <a>getCurrentDirectory</a>.
makeRelativeToCurrentDirectory :: OsPath -> IO OsPath

-- | Test whether the given path points to an existing filesystem object.
--   If the user lacks necessary permissions to search the parent
--   directories, this function may return false even if the file does
--   actually exist. This operation traverses symbolic links, so it can
--   return either True or False for them.
doesPathExist :: OsPath -> IO Bool

-- | The operation <a>doesFileExist</a> returns <a>True</a> if the argument
--   file exists and is not a directory, and <a>False</a> otherwise. This
--   operation traverses symbolic links, so it can return either True or
--   False for them.
doesFileExist :: OsPath -> IO Bool

-- | The operation <a>doesDirectoryExist</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. This operation traverses
--   symbolic links, so it can return either True or False for them.
doesDirectoryExist :: OsPath -> IO Bool

-- | Given the name or path of an executable file, <a>findExecutable</a>
--   searches for such a file in a list of system-defined locations, which
--   generally includes <tt>PATH</tt> and possibly more. The full path to
--   the executable is returned if found. For example, <tt>(findExecutable
--   "ghc")</tt> would normally give you the path to GHC.
--   
--   The path returned by <tt><a>findExecutable</a> name</tt> corresponds
--   to the program that would be executed by <tt><a>createProcess</a></tt>
--   when passed the same string (as a <tt>RawCommand</tt>, not a
--   <tt>ShellCommand</tt>), provided that <tt>name</tt> is not a relative
--   path with more than one segment.
--   
--   On Windows, <a>findExecutable</a> calls the Win32 function
--   <tt><a>SearchPath</a></tt>, which may search other places before
--   checking the directories in the <tt>PATH</tt> environment variable.
--   Where it actually searches depends on registry settings, but notably
--   includes the directory containing the current executable.
--   
--   On non-Windows platforms, the behavior is equivalent to
--   <a>findFileWith</a> using the search directories from the
--   <tt>PATH</tt> environment variable and testing each file for
--   executable permissions. Details can be found in the documentation of
--   <a>findFileWith</a>.
findExecutable :: OsString -> IO (Maybe OsPath)

-- | Search for executable files in a list of system-defined locations,
--   which generally includes <tt>PATH</tt> and possibly more.
--   
--   On Windows, this <i>only returns the first occurrence</i>, if any. Its
--   behavior is therefore equivalent to <a>findExecutable</a>.
--   
--   On non-Windows platforms, the behavior is equivalent to
--   <a>findExecutablesInDirectories</a> using the search directories from
--   the <tt>PATH</tt> environment variable. Details can be found in the
--   documentation of <a>findExecutablesInDirectories</a>.
findExecutables :: OsString -> IO [OsPath]

-- | Given a name or path, <a>findExecutable</a> appends the
--   <a>exeExtension</a> to the query and searches for executable files in
--   the list of given search directories and returns all occurrences.
--   
--   The behavior is equivalent to <a>findFileWith</a> using the given
--   search directories and testing each file for executable permissions.
--   Details can be found in the documentation of <a>findFileWith</a>.
--   
--   Unlike other similarly named functions,
--   <a>findExecutablesInDirectories</a> does not use <tt>SearchPath</tt>
--   from the Win32 API. The behavior of this function on Windows is
--   therefore equivalent to those on non-Windows platforms.
findExecutablesInDirectories :: [OsPath] -> OsString -> IO [OsPath]

-- | Search through the given list of directories for the given file.
--   
--   The behavior is equivalent to <a>findFileWith</a>, returning only the
--   first occurrence. Details can be found in the documentation of
--   <a>findFileWith</a>.
findFile :: [OsPath] -> OsString -> IO (Maybe OsPath)

-- | Search through the given list of directories for the given file and
--   returns all paths where the given file exists.
--   
--   The behavior is equivalent to <a>findFilesWith</a>. Details can be
--   found in the documentation of <a>findFilesWith</a>.
findFiles :: [OsPath] -> OsString -> IO [OsPath]

-- | Search through a given list of directories for a file that has the
--   given name and satisfies the given predicate and return the path of
--   the first occurrence. The directories are checked in a left-to-right
--   order.
--   
--   This is essentially a more performant version of <a>findFilesWith</a>
--   that always returns the first result, if any. Details can be found in
--   the documentation of <a>findFilesWith</a>.
findFileWith :: (OsPath -> IO Bool) -> [OsPath] -> OsString -> IO (Maybe OsPath)

-- | <tt>findFilesWith predicate dirs name</tt> searches through the list
--   of directories (<tt>dirs</tt>) for files that have the given
--   <tt>name</tt> and satisfy the given <tt>predicate</tt> and returns the
--   paths of those files. The directories are checked in a left-to-right
--   order and the paths are returned in the same order.
--   
--   If the <tt>name</tt> is a relative path, then for every search
--   directory <tt>dir</tt>, the function checks whether <tt>dir
--   <a>&lt;/&gt;</a> name</tt> exists and satisfies the predicate. If so,
--   <tt>dir <a>&lt;/&gt;</a> name</tt> is returned as one of the results.
--   In other words, the returned paths can be either relative or absolute
--   depending on the search directories were used. If there are no search
--   directories, no results are ever returned.
--   
--   If the <tt>name</tt> is an absolute path, then the function will
--   return a single result if the file exists and satisfies the predicate
--   and no results otherwise. This is irrespective of what search
--   directories were given.
findFilesWith :: (OsPath -> IO Bool) -> [OsPath] -> OsString -> IO [OsPath]

-- | Filename extension for executable files (including the dot if any)
--   (usually <tt>""</tt> on POSIX systems and <tt>".exe"</tt> on Windows
--   or OS/2).
exeExtension :: OsString

-- | Create a <i>file</i> symbolic link. The target path can be either
--   absolute or relative and need not refer to an existing file. The order
--   of arguments follows the POSIX convention.
--   
--   To remove an existing file symbolic link, use <a>removeFile</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is included
--   if supported by the operating system. On POSIX, the function uses
--   <tt>symlink</tt> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if the file system does not support symbolic links.
createFileLink :: OsPath -> OsPath -> IO ()

-- | Create a <i>directory</i> symbolic link. The target path can be either
--   absolute or relative and need not refer to an existing directory. The
--   order of arguments follows the POSIX convention.
--   
--   To remove an existing directory symbolic link, use
--   <a>removeDirectoryLink</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt> with
--   <tt>SYMBOLIC_LINK_FLAG_DIRECTORY</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is also
--   included if supported by the operating system. On POSIX, this is an
--   alias for <a>createFileLink</a> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if the file system does not support symbolic links.
createDirectoryLink :: OsPath -> OsPath -> IO ()

-- | Remove an existing <i>directory</i> symbolic link.
--   
--   On Windows, this is an alias for <a>removeDirectory</a>. On POSIX
--   systems, this is an alias for <a>removeFile</a>.
--   
--   See also: <a>removeFile</a>, which can remove an existing <i>file</i>
--   symbolic link.
removeDirectoryLink :: OsPath -> IO ()

-- | Check whether an existing <tt>path</tt> is a symbolic link. If
--   <tt>path</tt> is a regular file or directory, <a>False</a> is
--   returned. If <tt>path</tt> does not exist or is otherwise
--   inaccessible, an exception is thrown (see below).
--   
--   On Windows, this checks for <tt>FILE_ATTRIBUTE_REPARSE_POINT</tt>. In
--   addition to symbolic links, the function also returns true on junction
--   points. On POSIX systems, this checks for <tt>S_IFLNK</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isDoesNotExistError</a> if the symbolic link does not exist;
--   or</li>
--   <li><a>isPermissionError</a> if the user is not permitted to read the
--   symbolic link.</li>
--   </ul>
pathIsSymbolicLink :: OsPath -> IO Bool

-- | Retrieve the target path of either a file or directory symbolic link.
--   The returned path may not be absolute, may not exist, and may not even
--   be a valid path.
--   
--   On Windows systems, this calls <tt>DeviceIoControl</tt> with
--   <tt>FSCTL_GET_REPARSE_POINT</tt>. In addition to symbolic links, the
--   function also works on junction points. On POSIX systems, this calls
--   <tt>readlink</tt>.
--   
--   Windows-specific errors: This operation may fail with
--   <a>illegalOperationErrorType</a> if the file system does not support
--   symbolic links.
getSymbolicLinkTarget :: OsPath -> IO OsPath
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

-- | Get the permissions of a file or directory.
--   
--   On Windows, the <a>writable</a> permission corresponds to the
--   "read-only" attribute. The <a>executable</a> permission is set if the
--   file extension is of an executable file type. The <a>readable</a>
--   permission is always set.
--   
--   On POSIX systems, this returns the result of <tt>access</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: OsPath -> IO Permissions

-- | Set the permissions of a file or directory.
--   
--   On Windows, this is only capable of changing the <a>writable</a>
--   permission, which corresponds to the "read-only" attribute. Changing
--   the other permissions has no effect.
--   
--   On POSIX systems, this sets the <i>owner</i> permissions.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: OsPath -> Permissions -> IO ()

-- | Copy the permissions of one file to another. This reproduces the
--   permissions more accurately than using <a>getPermissions</a> followed
--   by <a>setPermissions</a>.
--   
--   On Windows, this copies only the read-only attribute.
--   
--   On POSIX systems, this is equivalent to <tt>stat</tt> followed by
--   <tt>chmod</tt>.
copyPermissions :: OsPath -> OsPath -> IO ()

-- | Obtain the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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.
getAccessTime :: OsPath -> IO UTCTime

-- | Obtain the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: OsPath -> IO UTCTime

-- | Change the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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>
setAccessTime :: OsPath -> UTCTime -> IO ()

-- | Change the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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>
--   <li><a>InvalidArgument</a> on FAT32 file system if the time is before
--   DOS Epoch (1 January 1980).</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>
setModificationTime :: OsPath -> UTCTime -> IO ()


-- | System-independent interface to directory manipulation (FilePath API).
module System.Directory

-- | <tt><a>createDirectory</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><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES]</tt></li>
--   <li><a>isAlreadyExistsError</a> 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><a>isDoesNotExistError</a> There is no path to the directory.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isFullError</a> 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>
createDirectory :: FilePath -> IO ()

-- | <tt><a>createDirectoryIfMissing</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.
createDirectoryIfMissing :: Bool -> FilePath -> IO ()

-- | <tt><a>removeDirectory</a> dir</tt> removes an existing directory
--   <i>dir</i>. 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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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>
removeDirectory :: FilePath -> IO ()

-- | <tt><a>removeDirectoryRecursive</a> dir</tt> removes an existing
--   directory <i>dir</i> together with its contents and subdirectories.
--   Within this directory, symbolic links are removed without affecting
--   their targets.
--   
--   On Windows, the operation fails if <i>dir</i> is a directory symbolic
--   link.
--   
--   This operation is reported to be flaky on Windows so retry logic may
--   be advisable. See:
--   <a>https://github.com/haskell/directory/pull/108</a>
removeDirectoryRecursive :: FilePath -> IO ()

-- | Removes a file or directory at <i>path</i> together with its contents
--   and subdirectories. Symbolic links are removed without affecting their
--   targets. If the path does not exist, nothing happens.
--   
--   Unlike other removal functions, this function will also attempt to
--   delete files marked as read-only or otherwise made unremovable due to
--   permissions. As a result, if the removal is incomplete, the
--   permissions or attributes on the remaining files may be altered. If
--   there are hard links in the directory, then permissions on all related
--   hard links may be altered.
--   
--   If an entry within the directory vanishes while
--   <tt>removePathForcibly</tt> is running, it is silently ignored.
--   
--   If an exception occurs while removing an entry,
--   <tt>removePathForcibly</tt> will still try to remove as many entries
--   as it can before failing with an exception. The first exception that
--   it encountered is re-thrown.
removePathForcibly :: FilePath -> IO ()

-- | <tt><a>renameDirectory</a> old new</tt> changes the name of an
--   existing directory from <i>old</i> to <i>new</i>. If the <i>new</i>
--   directory already exists, it is atomically replaced by the <i>old</i>
--   directory. If the <i>new</i> directory is neither the <i>old</i>
--   directory nor an alias of the <i>old</i> directory, it is removed as
--   if by <a>removeDirectory</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>renameDirectory</tt> fails if the <i>new</i>
--   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> The original directory does not exist,
--   or there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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>
renameDirectory :: FilePath -> FilePath -> IO ()

-- | <tt><a>listDirectory</a> dir</tt> returns a list of <i>all</i> entries
--   in <i>dir</i> without the special entries (<tt>.</tt> and
--   <tt>..</tt>).
--   
--   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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EACCES]</tt></li>
--   <li><a>isFullError</a> 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>
listDirectory :: FilePath -> IO [FilePath]

-- | Similar to <a>listDirectory</a>, but always includes the special
--   entries (<tt>.</tt> and <tt>..</tt>). (This applies to Windows as
--   well.)
--   
--   The operation may fail with the same exceptions as
--   <a>listDirectory</a>.
getDirectoryContents :: FilePath -> IO [FilePath]

-- | 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>).
--   
--   Note that <a>getCurrentDirectory</a> is not guaranteed to return the
--   same path received by <a>setCurrentDirectory</a>. On POSIX systems,
--   the path returned will always be fully dereferenced (not contain any
--   symbolic links). For more information, refer to the documentation of
--   <a>getcwd</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> There is no path referring to the
--   working directory. <tt>[EPERM, ENOENT, ESTALE...]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EACCES]</tt></li>
--   <li><a>isFullError</a> 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>
getCurrentDirectory :: IO FilePath

-- | 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> The directory does not exist.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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>
setCurrentDirectory :: FilePath -> IO ()

-- | 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>getCurrentDirectory</a> and <a>setCurrentDirectory</a>.
withCurrentDirectory :: FilePath -> IO a -> IO 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>getXdgDirectory</a> or
--   <a>getAppUserDataDirectory</a> instead.
--   
--   On Unix, <a>getHomeDirectory</a> behaves as follows:
--   
--   <ul>
--   <li>Returns $HOME env variable if set (including to an empty
--   string).</li>
--   <li>Otherwise uses home directory returned by <tt>getpwuid_r</tt>
--   using the UID of the current proccesses user. This basically reads the
--   <i>etc</i>passwd file. An empty home directory field is considered
--   valid.</li>
--   </ul>
--   
--   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>
getHomeDirectory :: IO FilePath

-- | 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> usually map to
--   the same directory.
data XdgDirectory

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.local/share</tt>. On Windows, the default 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. It uses the <tt>XDG_CONFIG_HOME</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>~/.config</tt>. On Windows, the default 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). It uses the
--   <tt>XDG_CACHE_HOME</tt> environment variable. On non-Windows systems,
--   the default is <tt>~/.cache</tt>. On Windows, the default 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

-- | For data that should persist between (application) restarts, but that
--   is not important or portable enough to the user that it should be
--   stored in <a>XdgData</a>. It uses the <tt>XDG_STATE_HOME</tt>
--   environment variable. On non-Windows sytems, the default is
--   <tt>~/.local/state</tt>. On Windows, the default is
--   <tt>%LOCALAPPDATA%</tt> (e.g.
--   <tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Local</tt>).
XdgState :: 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>getAppUserDataDirectory</a>, this function provides a more
--   fine-grained hierarchy as well as greater flexibility for the user.
--   
--   On Windows, <a>XdgData</a> and <a>XdgConfig</a> usually map to the
--   same directory unless overridden.
--   
--   Refer to the docs of <a>XdgDirectory</a> for more details.
--   
--   The second argument is usually the name of the application. Since it
--   will be integrated into the path, it must consist of valid path
--   characters. Note: if the second argument is an absolute path, it will
--   just return the second argument.
--   
--   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).
--   
--   As of 1.3.5.0, the environment variable is ignored if set to a
--   relative path, per revised XDG Base Directory Specification. See
--   <a>#100</a>.
getXdgDirectory :: XdgDirectory -> FilePath -> IO FilePath

-- | Search paths for various application data, as specified by the <a>XDG
--   Base Directory Specification</a>.
--   
--   The list of paths is split using <a>searchPathSeparator</a>, which on
--   Windows is a semicolon.
--   
--   Note: On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> usually
--   yield the same result.
data XdgDirectoryList

-- | For data files (e.g. images). It uses the <tt>XDG_DATA_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/usr/local/share/</tt> and <tt>/usr/share/</tt>. On Windows, the
--   default is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt> (e.g.
--   <tt>C:/ProgramData</tt>).
XdgDataDirs :: XdgDirectoryList

-- | For configuration files. It uses the <tt>XDG_CONFIG_DIRS</tt>
--   environment variable. On non-Windows systems, the default is
--   <tt>/etc/xdg</tt>. On Windows, the default is <tt>%PROGRAMDATA%</tt>
--   or <tt>%ALLUSERSPROFILE%</tt> (e.g. <tt>C:/ProgramData</tt>).
XdgConfigDirs :: XdgDirectoryList

-- | Similar to <a>getXdgDirectory</a> but retrieves the entire list of XDG
--   directories.
--   
--   On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> usually map to
--   the same list of directories unless overridden.
--   
--   Refer to the docs of <a>XdgDirectoryList</a> for more details.
getXdgDirectoryList :: XdgDirectoryList -> IO [FilePath]

-- | Obtain the path to a special directory for storing user-specific
--   application data (traditional Unix location). Newer applications may
--   prefer the the XDG-conformant location provided by
--   <a>getXdgDirectory</a> (<a>migration guide</a>).
--   
--   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>
getAppUserDataDirectory :: FilePath -> IO FilePath

-- | 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>getXdgDirectory</a> or
--   <a>getAppUserDataDirectory</a> instead.
--   
--   On Unix, <a>getUserDocumentsDirectory</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>
getUserDocumentsDirectory :: IO FilePath

-- | Returns the current directory for temporary files.
--   
--   On Unix, <a>getTemporaryDirectory</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.
getTemporaryDirectory :: IO FilePath

-- | <a>removeFile</a> <i>file</i> removes the directory entry for an
--   existing file <i>file</i>, where <i>file</i> 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> The file does not exist. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> 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 :: FilePath -> IO ()

-- | <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 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. On Windows, this does not support
--   renaming across different physical devices; if you are looking to do
--   so, consider using <a>copyFileWithMetadata</a> and <a>removeFile</a>.
--   
--   On Windows, this calls <tt>MoveFileEx</tt> with
--   <tt>MOVEFILE_REPLACE_EXISTING</tt> set, which is not guaranteed to be
--   atomic (<a>https://github.com/haskell/directory/issues/109</a>).
--   
--   On other platforms, this operation is atomic.
--   
--   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> The original file does not exist, or
--   there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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 :: FilePath -> FilePath -> IO ()

-- | Rename a file or directory. If the destination path already exists, it
--   is replaced atomically. The destination path must not point 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> The original file does not exist, or
--   there is no path to the target. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> The process has insufficient privileges
--   to perform the operation. <tt>[EROFS, EACCES, EPERM]</tt></li>
--   <li><a>isFullError</a> 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 the destination path refers to
--   an existing directory, or one of the parent segments in the
--   destination path is not a directory. <tt>[ENOTDIR, EISDIR, EINVAL,
--   EEXIST, ENOTEMPTY]</tt></li>
--   </ul>
renamePath :: FilePath -> FilePath -> IO ()

-- | Copy a file with its permissions. If the destination file already
--   exists, it is replaced atomically. Neither path may refer to an
--   existing directory. No exceptions are thrown if the permissions could
--   not be copied.
copyFile :: FilePath -> FilePath -> IO ()

-- | Copy a file with its associated metadata. If the destination file
--   already exists, it is overwritten. There is no guarantee of atomicity
--   in the replacement of the destination file. Neither path may refer to
--   an existing directory. If the source and/or destination are symbolic
--   links, the copy is performed on the targets of the links.
--   
--   On Windows, it behaves like the Win32 function <a>CopyFile</a>, which
--   copies various kinds of metadata including file attributes and
--   security resource properties.
--   
--   On Unix-like systems, permissions, access time, and modification time
--   are preserved. If possible, the owner and group are also preserved.
--   Note that the very act of copying can change the access time of the
--   source file, hence the access times of the two files may differ after
--   the operation completes.
copyFileWithMetadata :: FilePath -> FilePath -> IO ()

-- | Obtain the size of a file in bytes.
getFileSize :: FilePath -> IO Integer

-- | Make a path absolute, normalize the path, and remove as many
--   indirections from it as possible. Any trailing path separators are
--   discarded via <tt>dropTrailingPathSeparator</tt>. Additionally, on
--   Windows the letter case of the path is canonicalized.
--   
--   <b>Note</b>: This function is a very big hammer. If you only need an
--   absolute path, <a>makeAbsolute</a> is sufficient for removing
--   dependence on the current working directory.
--   
--   Indirections include the two special directories <tt>.</tt> and
--   <tt>..</tt>, as well as any symbolic links (and junction points on
--   Windows). The input path need not point to an existing file or
--   directory. Canonicalization is performed on the longest prefix of the
--   path that points to an existing file or directory. The remaining
--   portion of the path that does not point to an existing file or
--   directory will still be normalized, but case canonicalization and
--   indirection removal are skipped as they are impossible to do on a
--   nonexistent path.
--   
--   Most programs should not worry about the canonicity of a path. In
--   particular, despite the name, the function does not truly guarantee
--   canonicity of the returned path due to the presence of hard links,
--   mount points, etc.
--   
--   If the path points to an existing file or directory, then the output
--   path shall also point to the same file or directory, subject to the
--   condition that the relevant parts of the file system do not change
--   while the function is still running. In other words, the function is
--   definitively not atomic. The results can be utterly wrong if the
--   portions of the path change while this function is running.
--   
--   Since some indirections (symbolic links on all systems, <tt>..</tt> on
--   non-Windows systems, and junction points on Windows) are dependent on
--   the state of the existing filesystem, the function can only make a
--   conservative attempt by removing such indirections from the longest
--   prefix of the path that still points to an existing file or directory.
--   
--   Note that on Windows parent directories <tt>..</tt> are always fully
--   expanded before the symbolic links, as consistent with the rest of the
--   Windows API (such as <tt>GetFullPathName</tt>). In contrast, on POSIX
--   systems parent directories <tt>..</tt> are expanded alongside symbolic
--   links from left to right. To put this more concretely: if <tt>L</tt>
--   is a symbolic link for <tt>R/P</tt>, then on Windows <tt>L\..</tt>
--   refers to <tt>.</tt>, whereas on other operating systems <tt>L/..</tt>
--   refers to <tt>R</tt>.
--   
--   Similar to <a>normalise</a>, passing an empty path is equivalent to
--   passing the current directory.
--   
--   <tt>canonicalizePath</tt> can resolve at least 64 indirections in a
--   single path, more than what is supported by most operating systems.
--   Therefore, it may return the fully resolved path even though the
--   operating system itself would have long given up.
--   
--   On Windows XP or earlier systems, junction expansion is not performed
--   due to their lack of <tt>GetFinalPathNameByHandle</tt>.
--   
--   <i>Changes since 1.2.3.0:</i> The function has been altered to be more
--   robust and has the same exception behavior as <a>makeAbsolute</a>.
--   
--   <i>Changes since 1.3.0.0:</i> The function no longer preserves the
--   trailing path separator. File symbolic links that appear in the middle
--   of a path are properly dereferenced. Case canonicalization and
--   symbolic link expansion are now performed on Windows.
canonicalizePath :: FilePath -> IO FilePath

-- | Convert a path into an absolute path. If the given path is relative,
--   the current directory is prepended and then the combined result is
--   normalized. If the path is already absolute, the path is simply
--   normalized. The function preserves the presence or absence of the
--   trailing path separator unless the path refers to the root directory
--   <tt>/</tt>.
--   
--   If the path is already absolute, the operation never fails. Otherwise,
--   the operation may fail with the same exceptions as
--   <a>getCurrentDirectory</a>.
makeAbsolute :: FilePath -> IO FilePath

-- | Construct a path relative to the current directory, similar to
--   <tt>makeRelative</tt>.
--   
--   The operation may fail with the same exceptions as
--   <a>getCurrentDirectory</a>.
makeRelativeToCurrentDirectory :: FilePath -> IO FilePath

-- | Test whether the given path points to an existing filesystem object.
--   If the user lacks necessary permissions to search the parent
--   directories, this function may return false even if the file does
--   actually exist.
doesPathExist :: FilePath -> IO Bool

-- | 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 :: FilePath -> IO Bool

-- | The operation <a>doesDirectoryExist</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.
doesDirectoryExist :: FilePath -> IO Bool

-- | Given the name or path of an executable file, <a>findExecutable</a>
--   searches for such a file in a list of system-defined locations, which
--   generally includes <tt>PATH</tt> and possibly more. The full path to
--   the executable is returned if found. For example, <tt>(findExecutable
--   "ghc")</tt> would normally give you the path to GHC.
--   
--   The path returned by <tt><a>findExecutable</a> name</tt> corresponds
--   to the program that would be executed by <tt><a>createProcess</a></tt>
--   when passed the same string (as a <tt>RawCommand</tt>, not a
--   <tt>ShellCommand</tt>), provided that <tt>name</tt> is not a relative
--   path with more than one segment.
--   
--   On Windows, <a>findExecutable</a> calls the Win32 function
--   <tt><a>SearchPath</a></tt>, which may search other places before
--   checking the directories in the <tt>PATH</tt> environment variable.
--   Where it actually searches depends on registry settings, but notably
--   includes the directory containing the current executable.
--   
--   On non-Windows platforms, the behavior is equivalent to
--   <a>findFileWith</a> using the search directories from the
--   <tt>PATH</tt> environment variable and testing each file for
--   executable permissions. Details can be found in the documentation of
--   <a>findFileWith</a>.
findExecutable :: String -> IO (Maybe FilePath)

-- | Search for executable files in a list of system-defined locations,
--   which generally includes <tt>PATH</tt> and possibly more.
--   
--   On Windows, this <i>only returns the first occurrence</i>, if any. Its
--   behavior is therefore equivalent to <a>findExecutable</a>.
--   
--   On non-Windows platforms, the behavior is equivalent to
--   <a>findExecutablesInDirectories</a> using the search directories from
--   the <tt>PATH</tt> environment variable. Details can be found in the
--   documentation of <a>findExecutablesInDirectories</a>.
findExecutables :: String -> IO [FilePath]

-- | Given a name or path, <a>findExecutable</a> appends the
--   <a>exeExtension</a> to the query and searches for executable files in
--   the list of given search directories and returns all occurrences.
--   
--   The behavior is equivalent to <a>findFileWith</a> using the given
--   search directories and testing each file for executable permissions.
--   Details can be found in the documentation of <a>findFileWith</a>.
--   
--   Unlike other similarly named functions,
--   <a>findExecutablesInDirectories</a> does not use <tt>SearchPath</tt>
--   from the Win32 API. The behavior of this function on Windows is
--   therefore equivalent to those on non-Windows platforms.
findExecutablesInDirectories :: [FilePath] -> String -> IO [FilePath]

-- | Search through the given list of directories for the given file.
--   
--   The behavior is equivalent to <a>findFileWith</a>, returning only the
--   first occurrence. Details can be found in the documentation of
--   <a>findFileWith</a>.
findFile :: [FilePath] -> String -> IO (Maybe FilePath)

-- | Search through the given list of directories for the given file and
--   returns all paths where the given file exists.
--   
--   The behavior is equivalent to <a>findFilesWith</a>. Details can be
--   found in the documentation of <a>findFilesWith</a>.
findFiles :: [FilePath] -> String -> IO [FilePath]

-- | Search through a given list of directories for a file that has the
--   given name and satisfies the given predicate and return the path of
--   the first occurrence. The directories are checked in a left-to-right
--   order.
--   
--   This is essentially a more performant version of <a>findFilesWith</a>
--   that always returns the first result, if any. Details can be found in
--   the documentation of <a>findFilesWith</a>.
findFileWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO (Maybe FilePath)

-- | <tt>findFilesWith predicate dirs name</tt> searches through the list
--   of directories (<tt>dirs</tt>) for files that have the given
--   <tt>name</tt> and satisfy the given <tt>predicate</tt> and returns the
--   paths of those files. The directories are checked in a left-to-right
--   order and the paths are returned in the same order.
--   
--   If the <tt>name</tt> is a relative path, then for every search
--   directory <tt>dir</tt>, the function checks whether <tt>dir
--   <tt>&lt;/&gt;</tt> name</tt> exists and satisfies the predicate. If
--   so, <tt>dir <tt>&lt;/&gt;</tt> name</tt> is returned as one of the
--   results. In other words, the returned paths can be either relative or
--   absolute depending on the search directories were used. If there are
--   no search directories, no results are ever returned.
--   
--   If the <tt>name</tt> is an absolute path, then the function will
--   return a single result if the file exists and satisfies the predicate
--   and no results otherwise. This is irrespective of what search
--   directories were given.
findFilesWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO [FilePath]

-- | Filename extension for executable files (including the dot if any)
--   (usually <tt>""</tt> on POSIX systems and <tt>".exe"</tt> on Windows
--   or OS/2).
exeExtension :: String

-- | Create a <i>file</i> symbolic link. The target path can be either
--   absolute or relative and need not refer to an existing file. The order
--   of arguments follows the POSIX convention.
--   
--   To remove an existing file symbolic link, use <a>removeFile</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is included
--   if supported by the operating system. On POSIX, the function uses
--   <tt>symlink</tt> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if the file system does not support symbolic links.
createFileLink :: FilePath -> FilePath -> IO ()

-- | Create a <i>directory</i> symbolic link. The target path can be either
--   absolute or relative and need not refer to an existing directory. The
--   order of arguments follows the POSIX convention.
--   
--   To remove an existing directory symbolic link, use
--   <a>removeDirectoryLink</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt> with
--   <tt>SYMBOLIC_LINK_FLAG_DIRECTORY</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is also
--   included if supported by the operating system. On POSIX, this is an
--   alias for <a>createFileLink</a> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if the file system does not support symbolic links.
createDirectoryLink :: FilePath -> FilePath -> IO ()

-- | Remove an existing <i>directory</i> symbolic link.
--   
--   On Windows, this is an alias for <a>removeDirectory</a>. On POSIX
--   systems, this is an alias for <a>removeFile</a>.
--   
--   See also: <a>removeFile</a>, which can remove an existing <i>file</i>
--   symbolic link.
removeDirectoryLink :: FilePath -> IO ()

-- | Check whether an existing <tt>path</tt> is a symbolic link. If
--   <tt>path</tt> is a regular file or directory, <a>False</a> is
--   returned. If <tt>path</tt> does not exist or is otherwise
--   inaccessible, an exception is thrown (see below).
--   
--   On Windows, this checks for <tt>FILE_ATTRIBUTE_REPARSE_POINT</tt>. In
--   addition to symbolic links, the function also returns true on junction
--   points. On POSIX systems, this checks for <tt>S_IFLNK</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isDoesNotExistError</a> if the symbolic link does not exist;
--   or</li>
--   <li><a>isPermissionError</a> if the user is not permitted to read the
--   symbolic link.</li>
--   </ul>
pathIsSymbolicLink :: FilePath -> IO Bool

-- | Retrieve the target path of either a file or directory symbolic link.
--   The returned path may not be absolute, may not exist, and may not even
--   be a valid path.
--   
--   On Windows systems, this calls <tt>DeviceIoControl</tt> with
--   <tt>FSCTL_GET_REPARSE_POINT</tt>. In addition to symbolic links, the
--   function also works on junction points. On POSIX systems, this calls
--   <tt>readlink</tt>.
--   
--   Windows-specific errors: This operation may fail with
--   <a>illegalOperationErrorType</a> if the file system does not support
--   symbolic links.
getSymbolicLinkTarget :: FilePath -> IO FilePath
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

-- | Get the permissions of a file or directory.
--   
--   On Windows, the <a>writable</a> permission corresponds to the
--   "read-only" attribute. The <a>executable</a> permission is set if the
--   file extension is of an executable file type. The <a>readable</a>
--   permission is always set.
--   
--   On POSIX systems, this returns the result of <tt>access</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: FilePath -> IO Permissions

-- | Set the permissions of a file or directory.
--   
--   On Windows, this is only capable of changing the <a>writable</a>
--   permission, which corresponds to the "read-only" attribute. Changing
--   the other permissions has no effect.
--   
--   On POSIX systems, this sets the <i>owner</i> permissions.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: FilePath -> Permissions -> IO ()

-- | Copy the permissions of one file to another. This reproduces the
--   permissions more accurately than using <a>getPermissions</a> followed
--   by <a>setPermissions</a>.
--   
--   On Windows, this copies only the read-only attribute.
--   
--   On POSIX systems, this is equivalent to <tt>stat</tt> followed by
--   <tt>chmod</tt>.
copyPermissions :: FilePath -> FilePath -> IO ()

-- | Obtain the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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.
getAccessTime :: FilePath -> IO UTCTime

-- | Obtain the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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 :: FilePath -> IO UTCTime

-- | Change the time at which the file or directory was last accessed.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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>
setAccessTime :: FilePath -> UTCTime -> IO ()

-- | Change the time at which the file or directory was last modified.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> 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>
--   <li><a>InvalidArgument</a> on FAT32 file system if the time is before
--   DOS Epoch (1 January 1980).</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>
setModificationTime :: FilePath -> UTCTime -> IO ()

-- | <i>Deprecated: Use <a>pathIsSymbolicLink</a> instead</i>
isSymbolicLink :: FilePath -> IO Bool
