Copyright | © 2016 Julian Ospald |
---|---|
License | BSD3 |
Maintainer | Julian Ospald <hasufell@posteo.de> |
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
This module provides high-level IO related file operations like copy, delete, move and so on. It only operates on Path x which guarantees us well-typed paths. This is a thin wrapper over System.Posix.RawFilePath.Directory in 'hpath-directory'. It's encouraged to use this module.
Some of these operations are due to their nature not atomic, which means they may do multiple syscalls which form one context. Some of them also have to examine the filetypes explicitly before the syscalls, so a reasonable decision can be made. That means the result is undefined if another process changes that context while the non-atomic operation is still happening. However, where possible, as few syscalls as possible are used and the underlying exception handling is kept.
Note: BlockDevice
, CharacterDevice
, NamedPipe
and Socket
are ignored by some of the more high-level functions (like easyCopy
).
For other functions (like copyFile
), the behavior on these file types is
unreliable/unsafe. Check the documentation of those functions for details.
Synopsis
- data FileType
- data RecursiveErrorMode
- data CopyMode
- copyDirRecursive :: Path b1 -> Path b2 -> CopyMode -> RecursiveErrorMode -> IO ()
- recreateSymlink :: Path b1 -> Path b2 -> CopyMode -> IO ()
- copyFile :: Path b1 -> Path b2 -> CopyMode -> IO ()
- easyCopy :: Path b1 -> Path b2 -> CopyMode -> RecursiveErrorMode -> IO ()
- deleteFile :: Path b -> IO ()
- deleteDir :: Path b -> IO ()
- deleteDirRecursive :: Path b -> IO ()
- easyDelete :: Path b -> IO ()
- openFile :: Path b -> IO ProcessID
- executeFile :: Path b -> [ByteString] -> IO ProcessID
- createRegularFile :: FileMode -> Path b -> IO ()
- createDir :: FileMode -> Path b -> IO ()
- createDirIfMissing :: FileMode -> Path b -> IO ()
- createDirRecursive :: FileMode -> Path b -> IO ()
- createSymlink :: Path b -> ByteString -> IO ()
- renameFile :: Path b1 -> Path b2 -> IO ()
- moveFile :: Path b1 -> Path b2 -> CopyMode -> IO ()
- readFile :: Path b -> IO ByteString
- readFileStrict :: Path b -> IO ByteString
- readFileStream :: Path b -> IO (SerialT IO (Array Word8))
- writeFile :: Path b -> Maybe FileMode -> ByteString -> IO ()
- writeFileL :: Path b -> Maybe FileMode -> ByteString -> IO ()
- appendFile :: Path b -> ByteString -> IO ()
- newFilePerms :: FileMode
- newDirPerms :: FileMode
- doesExist :: Path b -> IO Bool
- doesFileExist :: Path b -> IO Bool
- doesDirectoryExist :: Path b -> IO Bool
- isReadable :: Path b -> IO Bool
- isWritable :: Path b -> IO Bool
- isExecutable :: Path b -> IO Bool
- canOpenDirectory :: Path b -> IO Bool
- getModificationTime :: Path b -> IO UTCTime
- setModificationTime :: Path b -> EpochTime -> IO ()
- setModificationTimeHiRes :: Path b -> POSIXTime -> IO ()
- getDirsFiles :: Path b -> IO [Path b]
- getDirsFiles' :: Path b -> IO [Path Rel]
- getDirsFilesStream :: (MonadCatch m, MonadAsync m, MonadMask m) => Path b -> IO (SerialT m (Path Rel))
- getFileType :: Path b -> IO FileType
- canonicalizePath :: Path b -> IO (Path Abs)
- toAbs :: Path b -> IO (Path Abs)
- withRawFilePath :: MonadThrow m => ByteString -> (Either (Path Abs) (Path Rel) -> m b) -> m b
- withHandle :: ByteString -> OpenMode -> ((Handle, Either (Path Abs) (Path Rel)) -> IO a) -> IO a
- module System.Posix.RawFilePath.Directory.Errors
Types
Instances
data RecursiveErrorMode #
The error mode for recursive operations.
On FailEarly
the whole operation fails immediately if any of the
recursive sub-operations fail, which is sort of the default
for IO operations.
On CollectFailures
skips errors in the recursion and keeps on recursing.
However all errors are collected in the RecursiveFailure
error type,
which is raised finally if there was any error. Also note that
RecursiveFailure
does not give any guarantees on the ordering
of the collected exceptions.
The mode for copy and file moves. Overwrite mode is usually not very well defined, but is a convenience shortcut.
File copying
:: Path b1 | source dir |
-> Path b2 | destination (parent dirs are not automatically created) |
-> CopyMode | |
-> RecursiveErrorMode | |
-> IO () |
Copies the contents of a directory recursively to the given destination, while preserving permissions. Does not follow symbolic links. This behaves more or less like the following, without descending into the destination if it already exists:
cp -a /source/dir /destination/somedir
For directory contents, this will ignore any file type that is not
RegularFile
, SymbolicLink
or Directory
.
For Overwrite
copy mode this does not prune destination directory
contents, so the destination might contain more files than the source after
the operation has completed. Permissions of existing directories are
fixed.
Safety/reliability concerns:
- not atomic
- examines filetypes explicitly
- an explicit check
throwDestinationInSource
is carried out for the top directory for basic sanity, because otherwise we might end up with an infinite copy loop... however, this operation is not carried out recursively (because it's slow)
Throws:
NoSuchThing
if source directory does not existPermissionDenied
if source directory can't be openedSameFile
if source and destination are the same file (HPathIOException
)DestinationInSource
if destination is contained in source (HPathIOException
)
Throws in FailEarly
RecursiveErrorMode only:
PermissionDenied
if output directory is not writableInvalidArgument
if source directory is wrong type (symlink)InappropriateType
if source directory is wrong type (regular file)
Throws in CollectFailures
RecursiveErrorMode only:
RecursiveFailure
if any of the recursive operations that are not part of the top-directory sanity-checks fail (HPathIOException
)
Throws in Strict
CopyMode only:
AlreadyExists
if destination already exists
Recreate a symlink.
In Overwrite
copy mode only files and empty directories are deleted.
Safety/reliability concerns:
Overwrite
mode is inherently non-atomic
Throws:
InvalidArgument
if source file is wrong type (not a symlink)PermissionDenied
if output directory cannot be written toPermissionDenied
if source directory cannot be openedSameFile
if source and destination are the same file (HPathIOException
)
Throws in Strict
mode only:
AlreadyExists
if destination already exists
Throws in Overwrite
mode only:
UnsatisfiedConstraints
if destination file is non-empty directory
Notes:
- calls
symlink
Copies the given regular file to the given destination.
Neither follows symbolic links, nor accepts them.
For "copying" symbolic links, use recreateSymlink
instead.
Note that this is still sort of a low-level function and doesn't
examine file types. For a more high-level version, use easyCopy
instead.
In Overwrite
copy mode only overwrites actual files, not directories.
In Strict
mode the destination file must not exist.
Safety/reliability concerns:
Overwrite
mode is not atomic- when used on
CharacterDevice
, reads the "contents" and copies them to a regular file, which might take indefinitely - when used on
BlockDevice
, may either read the "contents" and copy them to a regular file (potentially hanging indefinitely) or may create a regular empty destination file - when used on
NamedPipe
, will hang indefinitely
Throws:
NoSuchThing
if source file does not existNoSuchThing
if source file is a aSocket
PermissionDenied
if output directory is not writablePermissionDenied
if source directory can't be openedInvalidArgument
if source file is wrong type (symlink or directory)SameFile
if source and destination are the same file (HPathIOException
)
Throws in Strict
mode only:
AlreadyExists
if destination already exists
easyCopy :: Path b1 -> Path b2 -> CopyMode -> RecursiveErrorMode -> IO () Source #
Copies a regular file, directory or symbolic link. In case of a symbolic link it is just recreated, even if it points to a directory. Any other file type is ignored.
Safety/reliability concerns:
- examines filetypes explicitly
- calls
copyDirRecursive
for directories
File deletion
deleteFile :: Path b -> IO () Source #
Deletes the given file. Raises eISDIR
if run on a directory. Does not follow symbolic links.
Throws:
InappropriateType
for wrong file type (directory)NoSuchThing
if the file does not existPermissionDenied
if the directory cannot be read
Notes: calls unlink
deleteDir :: Path b -> IO () Source #
Deletes the given directory, which must be empty, never symlinks.
Throws:
InappropriateType
for wrong file type (symlink to directory)InappropriateType
for wrong file type (regular file)NoSuchThing
if directory does not existUnsatisfiedConstraints
if directory is not emptyPermissionDenied
if we can't open or write to parent directory
Notes: calls rmdir
deleteDirRecursive :: Path b -> IO () Source #
Deletes the given directory recursively. Does not follow symbolic
links. Tries deleteDir
first before attemtping a recursive
deletion.
On directory contents this behaves like easyDelete
and thus will ignore any file type that is not RegularFile
,
SymbolicLink
or Directory
.
Safety/reliability concerns:
- not atomic
- examines filetypes explicitly
Throws:
InappropriateType
for wrong file type (symlink to directory)InappropriateType
for wrong file type (regular file)NoSuchThing
if directory does not existPermissionDenied
if we can't open or write to parent directory
easyDelete :: Path b -> IO () Source #
Deletes a file, directory or symlink. In case of directory, performs recursive deletion. In case of a symlink, the symlink file is deleted. Any other file type is ignored.
Safety/reliability concerns:
- examines filetypes explicitly
- calls
deleteDirRecursive
for directories
File opening
openFile :: Path b -> IO ProcessID Source #
Opens a file appropriately by invoking xdg-open. The file type is not checked. This forks a process.
:: Path b | program |
-> [ByteString] | arguments |
-> IO ProcessID |
Executes a program with the given arguments. This forks a process.
File creation
createRegularFile :: FileMode -> Path b -> IO () Source #
Create an empty regular file at the given directory with the given filename.
Throws:
PermissionDenied
if output directory cannot be written toAlreadyExists
if destination already existsNoSuchThing
if any of the parent components of the path do not exist
createDir :: FileMode -> Path b -> IO () Source #
Create an empty directory at the given directory with the given filename.
Throws:
PermissionDenied
if output directory cannot be written toAlreadyExists
if destination already existsNoSuchThing
if any of the parent components of the path do not exist
createDirIfMissing :: FileMode -> Path b -> IO () Source #
Create an empty directory at the given directory with the given filename.
Throws:
PermissionDenied
if output directory cannot be written toNoSuchThing
if any of the parent components of the path do not exist
createDirRecursive :: FileMode -> Path b -> IO () Source #
Create an empty directory at the given directory with the given filename. All parent directories are created with the same filemode. This basically behaves like:
mkdir -p /some/dir
Safety/reliability concerns:
- not atomic
Throws:
PermissionDenied
if any part of the path components do not exist and cannot be written toAlreadyExists
if destination already exists and is *not* a directory
:: Path b | destination file |
-> ByteString | path the symlink points to |
-> IO () |
Create a symlink.
Throws:
PermissionDenied
if output directory cannot be written toAlreadyExists
if destination file already existsNoSuchThing
if any of the parent components of the path do not exist
Note: calls symlink
File renaming/moving
renameFile :: Path b1 -> Path b2 -> IO () Source #
Rename a given file with the provided filename. Destination and source
must be on the same device, otherwise eXDEV
will be raised.
Does not follow symbolic links, but renames the symbolic link file.
Safety/reliability concerns:
- has a separate set of exception handling, apart from the syscall
Throws:
NoSuchThing
if source file does not existPermissionDenied
if output directory cannot be written toPermissionDenied
if source directory cannot be openedUnsupportedOperation
if source and destination are on different devicesAlreadyExists
if destination already existsSameFile
if destination and source are the same file (HPathIOException
)
Note: calls rename
(but does not allow to rename over existing files)
Move a file. This also works across devices by copy-delete fallback. And also works on directories.
Does not follow symbolic links, but renames the symbolic link file.
Safety/reliability concerns:
Overwrite
mode is not atomic- copy-delete fallback is inherently non-atomic
- since this function calls
easyCopy
andeasyDelete
as a fallback torenameFile
, file types that are notRegularFile
,SymbolicLink
orDirectory
may be ignored - for
Overwrite
mode, the destination will be deleted (not recursively) before moving
Throws:
NoSuchThing
if source file does not existPermissionDenied
if output directory cannot be written toPermissionDenied
if source directory cannot be openedSameFile
if destination and source are the same file (HPathIOException
)
Throws in Strict
mode only:
AlreadyExists
if destination already exists
Notes:
- calls
rename
(but does not allow to rename over existing files)
File reading
readFile :: Path b -> IO ByteString Source #
Read the given file lazily.
Symbolic links are followed. File must exist.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
readFileStrict :: Path b -> IO ByteString Source #
Read the given file strictly into memory.
Symbolic links are followed. File must exist.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
readFileStream :: Path b -> IO (SerialT IO (Array Word8)) Source #
Open the given file as a filestream. Once the filestream is exits, the filehandle is cleaned up.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
File writing
:: Path b | |
-> Maybe FileMode | if Nothing, file must exist |
-> ByteString | |
-> IO () |
Write a given ByteString to a file, truncating the file beforehand. Follows symlinks.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
:: Path b | |
-> Maybe FileMode | if Nothing, file must exist |
-> ByteString | |
-> IO () |
Write a given lazy ByteString to a file, truncating the file beforehand. Follows symlinks.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
Note: uses streamly under the hood
appendFile :: Path b -> ByteString -> IO () Source #
Append a given ByteString to a file. The file must exist. Follows symlinks.
Throws:
InappropriateType
if file is not a regular file or a symlinkPermissionDenied
if we cannot read the file or the directory containting itNoSuchThing
if the file does not exist
File permissions
Default permissions for a new file.
newDirPerms :: FileMode #
Default permissions for a new directory.
File checks
doesExist :: Path b -> IO Bool Source #
Checks if the given file exists. Does not follow symlinks.
Only eNOENT is catched (and returns False).
doesFileExist :: Path b -> IO Bool Source #
Checks if the given file exists and is not a directory. Does not follow symlinks.
Only eNOENT is catched (and returns False).
doesDirectoryExist :: Path b -> IO Bool Source #
Checks if the given file exists and is a directory. Does not follow symlinks.
Only eNOENT is catched (and returns False).
isReadable :: Path b -> IO Bool Source #
Checks whether a file or folder is readable.
Only eACCES, eROFS, eTXTBSY, ePERM are catched (and return False).
Throws:
NoSuchThing
if the file does not exist
isWritable :: Path b -> IO Bool Source #
Checks whether a file or folder is writable.
Only eACCES, eROFS, eTXTBSY, ePERM are catched (and return False).
Throws:
NoSuchThing
if the file does not exist
isExecutable :: Path b -> IO Bool Source #
Checks whether a file or folder is executable.
Only eACCES, eROFS, eTXTBSY, ePERM are catched (and return False).
Throws:
NoSuchThing
if the file does not exist
canOpenDirectory :: Path b -> IO Bool Source #
Checks whether the directory at the given path exists and can be
opened. This invokes openDirStream
which follows symlinks.
File times
Directory reading
Gets all filenames of the given directory. This excludes "." and "..". This version does not follow symbolic links.
The contents are not sorted and there is no guarantee on the ordering.
Throws:
NoSuchThing
if directory does not existInappropriateType
if file type is wrong (file)InappropriateType
if file type is wrong (symlink to file)InappropriateType
if file type is wrong (symlink to dir)PermissionDenied
if directory cannot be openedPathParseException
if a filename could not be parsed (should never happen)
Like getDirsFiles
, but returns the filename only, instead
of prepending the base path.
getDirsFilesStream :: (MonadCatch m, MonadAsync m, MonadMask m) => Path b -> IO (SerialT m (Path Rel)) Source #
Like getDirsFiles'
, except returning a Stream.
Filetype operations
getFileType :: Path b -> IO FileType Source #
Get the file type of the file located at the given path. Does not follow symbolic links.
Throws:
NoSuchThing
if the file does not existPermissionDenied
if any part of the path is not accessible
Others
canonicalizePath :: Path b -> IO (Path Abs) Source #
Applies realpath
on the given path.
Throws:
NoSuchThing
if the file at the given path does not existNoSuchThing
if the symlink is brokenPathParseException
if realpath does not return an absolute path
toAbs :: Path b -> IO (Path Abs) Source #
Converts any path to an absolute path. This is done in the following way:
- if the path is already an absolute one, just return it
- if it's a relative path, prepend the current directory to it
withRawFilePath :: MonadThrow m => ByteString -> (Either (Path Abs) (Path Rel) -> m b) -> m b Source #
Helper function to use the Path library without
buying into the Path type too much. This uses parseAny
under the hood and may throw PathParseException
.
Throws:
PathParseException
if the bytestring could neither be parsed as relative or absolute Path
withHandle :: ByteString -> OpenMode -> ((Handle, Either (Path Abs) (Path Rel)) -> IO a) -> IO a Source #
Convenience function to open the path as a handle.
If the file does not exist, it will be created with newFilePerms
.
Throws:
PathParseException
if the bytestring could neither be parsed as relative or absolute Path