-- 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.2.2.0


-- | System-independent interface to directory manipulation.
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> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES]</tt></li>
--   <li><a>isAlreadyExistsError</a> / <tt>AlreadyExists</tt> The operand
--   refers to a directory that already exists. <tt> [EEXIST]</tt></li>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><tt>NoSuchThing</tt> There is no path to the directory.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources (virtual memory,
--   process file descriptors, physical disk space, etc.) are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><a>InappropriateType</a> 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> / <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
--   EEXIST]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   removal in this situation. <tt>[EINVAL]</tt></li>
--   <li><a>InappropriateType</a> 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.
--   Symbolic links are removed without affecting their the targets.
removeDirectoryRecursive :: 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> / <tt>NoSuchThing</tt> The original
--   directory does not exist, or there is no path to the target.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
--   EEXIST]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   renaming in this situation. <tt>[EINVAL, EXDEV]</tt></li>
--   <li><a>InappropriateType</a> Either path refers to an existing
--   non-directory object. <tt>[ENOTDIR, EISDIR]</tt></li>
--   </ul>
renameDirectory :: FilePath -> FilePath -> IO ()

-- | <tt><a>getDirectoryContents</a> dir</tt> returns a list of <i>all</i>
--   entries in <i>dir</i>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EMFILE, ENFILE]</tt></li>
--   <li><a>InappropriateType</a> The path refers to an existing
--   non-directory object. <tt>[ENOTDIR]</tt></li>
--   </ul>
getDirectoryContents :: FilePath -> IO [FilePath]

-- | If the operating system has a notion of current directories,
--   <a>getCurrentDirectory</a> returns an absolute path to the current
--   directory of the calling process.
--   
--   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> / <tt>NoSuchThing</tt> There is no path
--   referring to the current directory. <tt>[EPERM, ENOENT,
--   ESTALE...]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation.</li>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of current directory.</li>
--   </ul>
--   
--   Note that in a concurrent program, the current directory is global
--   state shared between all threads of the process. When using filesystem
--   operations from multiple threads, it is therefore highly recommended
--   to use absolute rather than relative <a>FilePath</a>s.
getCurrentDirectory :: IO FilePath

-- | If the operating system has a notion of current directories,
--   <tt><a>setCurrentDirectory</a> dir</tt> changes the current directory
--   of the calling process to <i>dir</i>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> The operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
--   does not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The operating system has no notion
--   of current directory, or the current directory cannot be dynamically
--   changed.</li>
--   <li><a>InappropriateType</a> The path refers to an existing
--   non-directory object. <tt>[ENOTDIR]</tt></li>
--   </ul>
--   
--   Note that in a concurrent program, the current directory is global
--   state shared between all threads of the process. When using filesystem
--   operations from multiple threads, it is therefore highly recommended
--   to use absolute rather than relative <a>FilePath</a>s.
setCurrentDirectory :: FilePath -> IO ()

-- | 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>getAppUserDataDirectory</a>
--   instead.
--   
--   On Unix, <a>getHomeDirectory</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:/Documents And
--   Settings/user</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

-- | Returns the pathname of a directory in which application-specific data
--   for the current user can be stored. The result of
--   <a>getAppUserDataDirectory</a> for a given application is specific to
--   the current user.
--   
--   The argument should be the name of the application, which will be used
--   to construct the pathname (so avoid using unusual characters that
--   might result in an invalid pathname).
--   
--   Note: the directory may not actually exist, and may need to be created
--   first. It is expected that the parent directory exists and is
--   writable.
--   
--   On Unix, this function returns <tt>$HOME/.appName</tt>. On Windows, a
--   typical path might be
--   
--   <pre>
--   C:/Users/user/AppData/Roaming/appName
--   </pre>
--   
--   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 :: String -> 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>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:/Documents And
--   Settings/user/My 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> / <tt>NoSuchThing</tt> The file does
--   not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY]</tt></li>
--   <li><a>InappropriateType</a> 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 atomically replaced by the <i>old</i>
--   object. Neither path may refer to an existing directory. A conformant
--   implementation need not support renaming files in all situations (e.g.
--   renaming across different physical devices), but the constraints must
--   be documented.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><tt>HardwareFault</tt> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><tt>InvalidArgument</tt> Either operand is not a valid file name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
--   file does not exist, or there is no path to the target. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
--   has insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES, EPERM]</tt></li>
--   <li><tt>ResourceExhausted</tt> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
--   constraints are not satisfied. <tt>[EBUSY]</tt></li>
--   <li><tt>UnsupportedOperation</tt> The implementation does not support
--   renaming in this situation. <tt>[EXDEV]</tt></li>
--   <li><a>InappropriateType</a> Either path refers to an existing
--   directory. <tt>[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]</tt></li>
--   </ul>
renameFile :: FilePath -> FilePath -> IO ()

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

-- | Canonicalize the path of an existing file or directory. The intent is
--   that two paths referring to the same file/directory will map to the
--   same canonicalized path.
--   
--   <b>Note</b>: if you only require an absolute path, consider using
--   <tt><a>makeAbsolute</a></tt> instead, which is more reliable and does
--   not have unspecified behavior on nonexistent paths.
--   
--   It is impossible to guarantee that the implication (same file/dir
--   &lt;=&gt; same canonicalized path) holds in either direction: this
--   function can make only a best-effort attempt.
--   
--   The precise behaviour is that of the POSIX <tt>realpath</tt> function
--   (or <tt>GetFullPathNameW</tt> on Windows). In particular, the
--   behaviour on paths that don't exist can vary from platform to
--   platform. Some platforms do not alter the input, some do, and some
--   throw an exception.
--   
--   An empty path is considered to be equivalent to the current directory.
--   
--   <i>Known bug(s)</i>: on Windows, this function does not resolve
--   symbolic links.
canonicalizePath :: FilePath -> IO FilePath

-- | Make a path absolute by prepending the current directory (if it isn't
--   already absolute) and applying <tt><a>normalise</a></tt> to the
--   result.
--   
--   The operation may fail with the same exceptions as
--   <tt><a>getCurrentDirectory</a></tt>.
--   
--   <i>Since: 1.2.2.0</i>
makeAbsolute :: FilePath -> IO FilePath

-- | <a>makeRelative</a> the current directory.
makeRelativeToCurrentDirectory :: FilePath -> IO FilePath

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

-- | Given a file name, searches for the file and returns a list of all
--   occurences that are executable.
--   
--   <i>Since: 1.2.2.0</i>
findExecutables :: String -> IO [FilePath]

-- | Search through the given set of directories for the given file. Used
--   by <a>findExecutable</a> on non-windows platforms.
findFile :: [FilePath] -> String -> IO (Maybe FilePath)

-- | Search through the given set of directories for the given file and
--   returns a list of paths where the given file exists.
--   
--   <i>Since: 1.2.1.0</i>
findFiles :: [FilePath] -> String -> IO [FilePath]

-- | Search through the given set of directories for the given file and
--   with the given property (usually permissions) and returns a list of
--   paths where the given file exists and has the property.
--   
--   <i>Since: 1.2.1.0</i>
findFilesWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO [FilePath]

-- | 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
data Permissions
emptyPermissions :: Permissions
readable :: Permissions -> Bool
writable :: Permissions -> Bool
executable :: Permissions -> Bool
searchable :: Permissions -> Bool
setOwnerReadable :: Bool -> Permissions -> Permissions
setOwnerWritable :: Bool -> Permissions -> Permissions
setOwnerExecutable :: Bool -> Permissions -> Permissions
setOwnerSearchable :: Bool -> Permissions -> Permissions

-- | The <a>getPermissions</a> operation returns the permissions for the
--   file or directory.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><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

-- | The <a>setPermissions</a> operation sets the permissions for the file
--   or directory.
--   
--   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 ()
copyPermissions :: FilePath -> FilePath -> IO ()

-- | The <a>getModificationTime</a> operation returns the clock 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 access
--   the modification time; or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
--   
--   Note: 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 for unix systems, and <tt>Win32-2.3.1.0</tt> or later for
--   windows systems. Of course this also requires that the underlying file
--   system supports such high resolution timestamps.
getModificationTime :: FilePath -> IO UTCTime
instance GHC.Show.Show System.Directory.DirectoryType
instance GHC.Read.Read System.Directory.DirectoryType
instance GHC.Classes.Ord System.Directory.DirectoryType
instance GHC.Classes.Eq System.Directory.DirectoryType
instance GHC.Enum.Enum System.Directory.DirectoryType
instance GHC.Show.Show System.Directory.Permissions
instance GHC.Read.Read System.Directory.Permissions
instance GHC.Classes.Ord System.Directory.Permissions
instance GHC.Classes.Eq System.Directory.Permissions
