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


-- | library for directory handling
--   
--   This package provides a library for handling directories.
@package directory
@version 1.1.0.2


-- | 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> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation. <tt>[EROFS,
--   EACCES]</tt></li>
--   <li><a>isAlreadyExistsError</a> / <a>AlreadyExists</a> The operand
--   refers to a directory that already exists. <tt> [EEXIST]</tt></li>
--   <li><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> The operand is not a valid directory name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>NoSuchThing</a> There is no path to the directory. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><a>ResourceExhausted</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><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><a>HardwareFault</a> A physical I/O error has occurred. EIO</li>
--   <li><a>InvalidArgument</a> The operand is not a valid directory name.
--   [ENAMETOOLONG, ELOOP]</li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The directory does
--   not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation. <tt>[EROFS, EACCES,
--   EPERM]</tt></li>
--   <li><a>UnsatisfiedConstraints</a> Implementation-dependent constraints
--   are not satisfied. <tt>[EBUSY, ENOTEMPTY, EEXIST]</tt></li>
--   <li><a>UnsupportedOperation</a> 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 content and all subdirectories.
--   Be careful, if the directory contains symlinks, the function will
--   follow them.
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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> Either operand is not a valid directory
--   name. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The original
--   directory does not exist, or there is no path to the target.
--   <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation. <tt>[EROFS, EACCES,
--   EPERM]</tt></li>
--   <li><a>ResourceExhausted</a> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><a>UnsatisfiedConstraints</a> Implementation-dependent constraints
--   are not satisfied. <tt>[EBUSY, ENOTEMPTY, EEXIST]</tt></li>
--   <li><a>UnsupportedOperation</a> 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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> The operand is not a valid directory name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The directory does
--   not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><a>ResourceExhausted</a> 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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> There is no path
--   referring to the current directory. <tt>[EPERM, ENOENT,
--   ESTALE...]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><a>ResourceExhausted</a> Insufficient resources are available to
--   perform the operation.</li>
--   <li><a>UnsupportedOperation</a> 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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> The operand is not a valid directory name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The directory does
--   not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation.
--   <tt>[EACCES]</tt></li>
--   <li><a>UnsupportedOperation</a> 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:<i>Documents And
--   Settings</i>user</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>UnsupportedOperation</a> 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:/Documents And Settings/user/Application Data/appName
--   </pre>
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>UnsupportedOperation</a> 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><a>UnsupportedOperation</a> 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><a>UnsupportedOperation</a> 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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> The operand is not a valid file name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The file does not
--   exist. <tt>[ENOENT, ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation. <tt>[EROFS, EACCES,
--   EPERM]</tt></li>
--   <li><a>UnsatisfiedConstraints</a> 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><a>HardwareFault</a> A physical I/O error has occurred.
--   <tt>[EIO]</tt></li>
--   <li><a>InvalidArgument</a> Either operand is not a valid file name.
--   <tt>[ENAMETOOLONG, ELOOP]</tt></li>
--   <li><a>isDoesNotExistError</a> / <a>NoSuchThing</a> The original file
--   does not exist, or there is no path to the target. <tt>[ENOENT,
--   ENOTDIR]</tt></li>
--   <li><a>isPermissionError</a> / <a>PermissionDenied</a> The process has
--   insufficient privileges to perform the operation. <tt>[EROFS, EACCES,
--   EPERM]</tt></li>
--   <li><a>ResourceExhausted</a> Insufficient resources are available to
--   perform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
--   <li><a>UnsatisfiedConstraints</a> Implementation-dependent constraints
--   are not satisfied. <tt>[EBUSY]</tt></li>
--   <li><a>UnsupportedOperation</a> 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 ()

-- | Given path referring to a file or directory, returns a canonicalized
--   path, with the intent that two paths referring to the same
--   file/directory will map to the same canonicalized path. Note that it
--   is impossible to guarantee that the implication (same file/dir
--   &lt;=&gt; same canonicalizedPath) holds in either direction: this
--   function can make only a best-effort attempt.
canonicalizePath :: 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)

-- | 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 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>
getModificationTime :: FilePath -> IO ClockTime
instance Eq Permissions
instance Ord Permissions
instance Read Permissions
instance Show Permissions