Portability | portable |
---|---|
Stability | stable |
Maintainer | libraries@haskell.org |
System.Directory
Contents
Description
System-independent interface to directory manipulation.
- createDirectory :: FilePath -> IO ()
- createDirectoryIfMissing :: Bool -> FilePath -> IO ()
- removeDirectory :: FilePath -> IO ()
- removeDirectoryRecursive :: FilePath -> IO ()
- renameDirectory :: FilePath -> FilePath -> IO ()
- getDirectoryContents :: FilePath -> IO [FilePath]
- getCurrentDirectory :: IO FilePath
- setCurrentDirectory :: FilePath -> IO ()
- getHomeDirectory :: IO FilePath
- getAppUserDataDirectory :: String -> IO FilePath
- getUserDocumentsDirectory :: IO FilePath
- getTemporaryDirectory :: IO FilePath
- removeFile :: FilePath -> IO ()
- renameFile :: FilePath -> FilePath -> IO ()
- copyFile :: FilePath -> FilePath -> IO ()
- canonicalizePath :: FilePath -> IO FilePath
- makeRelativeToCurrentDirectory :: FilePath -> IO FilePath
- findExecutable :: String -> IO (Maybe FilePath)
- doesFileExist :: FilePath -> IO Bool
- 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
- getPermissions :: FilePath -> IO Permissions
- setPermissions :: FilePath -> Permissions -> IO ()
- copyPermissions :: FilePath -> FilePath -> IO ()
- getModificationTime :: FilePath -> IO ClockTime
Documentation
A directory contains a series of entries, each of which is a named
reference to a file system object (file, directory etc.). Some
entries may be hidden, inaccessible, or have some administrative
function (e.g. .
or `..' under POSIX
http://www.opengroup.org/onlinepubs/009695399/), but in
this standard all such entries are considered to form part of the
directory contents. Entries in sub-directories are not, however,
considered to form part of the directory contents.
Each file system object is referenced by a path. There is normally at least one absolute path to each file system object. In some operating systems, it may also be possible to have paths which are relative to the current directory.
Actions on directories
createDirectory :: FilePath -> IO ()Source
creates a new directory createDirectory
dirdir
which is
initially empty, or as near to empty as the operating system
allows.
The operation may fail with:
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EROFS, EACCES]
-
isAlreadyExistsError
/AlreadyExists
The operand refers to a directory that already exists.[EEXIST]
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
The operand is not a valid directory name.[ENAMETOOLONG, ELOOP]
-
NoSuchThing
There is no path to the directory.[ENOENT, ENOTDIR]
-
ResourceExhausted
Insufficient resources (virtual memory, process file descriptors, physical disk space, etc.) are available to perform the operation.[EDQUOT, ENOSPC, ENOMEM, EMLINK]
-
InappropriateType
The path refers to an existing non-directory object.[EEXIST]
createDirectoryIfMissingSource
Arguments
:: Bool | Create its parents too? |
-> FilePath | The path to the directory you want to make |
-> IO () |
creates a new directory
createDirectoryIfMissing
parents dirdir
if it doesn't exist. If the first argument is True
the function will also create all parent directories if they are missing.
removeDirectory :: FilePath -> IO ()Source
removes an existing directory dir. 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).
removeDirectory
dir
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred. EIO -
InvalidArgument
The operand is not a valid directory name. [ENAMETOOLONG, ELOOP] -
isDoesNotExistError
/NoSuchThing
The directory does not exist.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EROFS, EACCES, EPERM]
-
UnsatisfiedConstraints
Implementation-dependent constraints are not satisfied.[EBUSY, ENOTEMPTY, EEXIST]
-
UnsupportedOperation
The implementation does not support removal in this situation.[EINVAL]
-
InappropriateType
The operand refers to an existing non-directory object.[ENOTDIR]
removeDirectoryRecursive :: FilePath -> IO ()Source
removes an existing directory dir
together with its content and all subdirectories. Be careful,
if the directory contains symlinks, the function will follow them.
removeDirectoryRecursive
dir
renameDirectory :: FilePath -> FilePath -> IO ()Source
changes the name of an existing
directory from old to new. If the new directory
already exists, it is atomically replaced by the old directory.
If the new directory is neither the old directory nor an
alias of the old directory, it is removed as if by
renameDirectory
old newremoveDirectory
. 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, renameDirectory
fails if the new directory already
exists.
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
Either operand is not a valid directory name.[ENAMETOOLONG, ELOOP]
-
isDoesNotExistError
/NoSuchThing
The original directory does not exist, or there is no path to the target.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EROFS, EACCES, EPERM]
-
ResourceExhausted
Insufficient resources are available to perform the operation.[EDQUOT, ENOSPC, ENOMEM, EMLINK]
-
UnsatisfiedConstraints
Implementation-dependent constraints are not satisfied.[EBUSY, ENOTEMPTY, EEXIST]
-
UnsupportedOperation
The implementation does not support renaming in this situation.[EINVAL, EXDEV]
-
InappropriateType
Either path refers to an existing non-directory object.[ENOTDIR, EISDIR]
getDirectoryContents :: FilePath -> IO [FilePath]Source
returns a list of all entries
in dir.
getDirectoryContents
dir
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
The operand is not a valid directory name.[ENAMETOOLONG, ELOOP]
-
isDoesNotExistError
/NoSuchThing
The directory does not exist.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EACCES]
-
ResourceExhausted
Insufficient resources are available to perform the operation.[EMFILE, ENFILE]
-
InappropriateType
The path refers to an existing non-directory object.[ENOTDIR]
getCurrentDirectory :: IO FilePathSource
If the operating system has a notion of current directories,
getCurrentDirectory
returns an absolute path to the
current directory of the calling process.
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
isDoesNotExistError
/NoSuchThing
There is no path referring to the current directory.[EPERM, ENOENT, ESTALE...]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EACCES]
-
ResourceExhausted
Insufficient resources are available to perform the operation. -
UnsupportedOperation
The operating system has no notion of current directory.
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 FilePath
s.
setCurrentDirectory :: FilePath -> IO ()Source
If the operating system has a notion of current directories,
changes the current
directory of the calling process to dir.
setCurrentDirectory
dir
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
The operand is not a valid directory name.[ENAMETOOLONG, ELOOP]
-
isDoesNotExistError
/NoSuchThing
The directory does not exist.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EACCES]
-
UnsupportedOperation
The operating system has no notion of current directory, or the current directory cannot be dynamically changed. -
InappropriateType
The path refers to an existing non-directory object.[ENOTDIR]
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 FilePath
s.
Pre-defined directories
getHomeDirectory :: IO FilePathSource
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 getAppUserDataDirectory
instead.
On Unix, getHomeDirectory
returns the value of the HOME
environment variable. On Windows, the system is queried for a
suitable path; a typical path might be
C:Documents And Settingsuser
.
The operation may fail with:
-
UnsupportedOperation
The operating system has no notion of home directory. -
isDoesNotExistError
The home directory for the current user does not exist, or cannot be found.
getAppUserDataDirectory :: String -> IO FilePathSource
Returns the pathname of a directory in which application-specific
data for the current user can be stored. The result of
getAppUserDataDirectory
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 $HOME/.appName
. On Windows, a
typical path might be
C:/Documents And Settings/user/Application Data/appName
The operation may fail with:
-
UnsupportedOperation
The operating system has no notion of application-specific data directory. -
isDoesNotExistError
The home directory for the current user does not exist, or cannot be found.
getUserDocumentsDirectory :: IO FilePathSource
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 getAppUserDataDirectory
instead.
On Unix, getUserDocumentsDirectory
returns the value of the HOME
environment variable. On Windows, the system is queried for a
suitable path; a typical path might be
C:/Documents and Settings/user/My Documents
.
The operation may fail with:
-
UnsupportedOperation
The operating system has no notion of document directory. -
isDoesNotExistError
The document directory for the current user does not exist, or cannot be found.
getTemporaryDirectory :: IO FilePathSource
Returns the current directory for temporary files.
On Unix, getTemporaryDirectory
returns the value of the TMPDIR
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:
- TMP environment variable.
- TEMP environment variable.
- USERPROFILE environment variable.
- The Windows directory
The operation may fail with:
-
UnsupportedOperation
The operating system has no notion of temporary directory.
The function doesn't verify whether the path exists.
Actions on files
removeFile :: FilePath -> IO ()Source
removeFile
file removes the directory entry for an existing file
file, where file 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:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
The operand is not a valid file name.[ENAMETOOLONG, ELOOP]
-
isDoesNotExistError
/NoSuchThing
The file does not exist.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EROFS, EACCES, EPERM]
-
UnsatisfiedConstraints
Implementation-dependent constraints are not satisfied.[EBUSY]
-
InappropriateType
The operand refers to an existing directory.[EPERM, EINVAL]
renameFile :: FilePath -> FilePath -> IO ()Source
changes the name of an existing file system
object from old to new. If the new object already
exists, it is atomically replaced by the old 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.
renameFile
old new
The operation may fail with:
-
HardwareFault
A physical I/O error has occurred.[EIO]
-
InvalidArgument
Either operand is not a valid file name.[ENAMETOOLONG, ELOOP]
-
isDoesNotExistError
/NoSuchThing
The original file does not exist, or there is no path to the target.[ENOENT, ENOTDIR]
-
isPermissionError
/PermissionDenied
The process has insufficient privileges to perform the operation.[EROFS, EACCES, EPERM]
-
ResourceExhausted
Insufficient resources are available to perform the operation.[EDQUOT, ENOSPC, ENOMEM, EMLINK]
-
UnsatisfiedConstraints
Implementation-dependent constraints are not satisfied.[EBUSY]
-
UnsupportedOperation
The implementation does not support renaming in this situation.[EXDEV]
-
InappropriateType
Either path refers to an existing directory.[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]
copyFile :: FilePath -> FilePath -> IO ()Source
copies the existing file from old to new.
If the new file already exists, it is atomically replaced by the old file.
Neither path may refer to an existing directory. The permissions of old are
copied to new, if possible.
copyFile
old new
canonicalizePath :: FilePath -> IO FilePathSource
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 <=> same canonicalizedPath) holds in either direction: this function can make only a best-effort attempt.
makeRelativeToCurrentDirectory :: FilePath -> IO FilePathSource
makeRelative
the current directory.
findExecutable :: String -> IO (Maybe FilePath)Source
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 findExecutable
corresponds to the
program that would be executed by System.Process.createProcess
when passed the same string (as a RawCommand, not a ShellCommand).
On Windows, findExecutable
calls the Win32 function SearchPath
,
which may search other places before checking the directories in
PATH
. Where it actually searches depends on registry settings,
but notably includes the directory containing the current
executable. See
http://msdn.microsoft.com/en-us/library/aa365527.aspx for more
details.
Existence tests
doesFileExist :: FilePath -> IO BoolSource
The operation doesFileExist
returns True
if the argument file exists and is not a directory, and False
otherwise.
doesDirectoryExist :: FilePath -> IO BoolSource
The operation doesDirectoryExist
returns True
if the argument file
exists and is a directory, and False
otherwise.
Permissions
The Permissions
type is used to record whether certain operations are
permissible on a file/directory. getPermissions
and setPermissions
get and set these permissions, respectively. Permissions apply both to
files and directories. For directories, the executable field will be
False
, and for files the searchable field will be False
. Note that
directories may be searchable without being readable, if permission has
been given to use them as part of a path, but not to examine the
directory contents.
Note that to change some, but not all permissions, a construct on the following lines must be used.
makeReadable f = do p <- getPermissions f setPermissions f (p {readable = True})
data Permissions Source
Instances
readable :: Permissions -> BoolSource
writable :: Permissions -> BoolSource
executable :: Permissions -> BoolSource
searchable :: Permissions -> BoolSource
setOwnerReadable :: Bool -> Permissions -> PermissionsSource
setOwnerWritable :: Bool -> Permissions -> PermissionsSource
getPermissions :: FilePath -> IO PermissionsSource
The getPermissions
operation returns the
permissions for the file or directory.
The operation may fail with:
-
isPermissionError
if the user is not permitted to access the permissions; or -
isDoesNotExistError
if the file or directory does not exist.
setPermissions :: FilePath -> Permissions -> IO ()Source
The setPermissions
operation sets the
permissions for the file or directory.
The operation may fail with:
-
isPermissionError
if the user is not permitted to set the permissions; or -
isDoesNotExistError
if the file or directory does not exist.
copyPermissions :: FilePath -> FilePath -> IO ()Source
Timestamps
getModificationTime :: FilePath -> IO ClockTimeSource
The getModificationTime
operation returns the
clock time at which the file or directory was last modified.
The operation may fail with:
-
isPermissionError
if the user is not permitted to access the modification time; or -
isDoesNotExistError
if the file or directory does not exist.