-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Alternative to 'directory' package with ByteString based filepaths -- -- This provides a safer alternative to the directory package. -- FilePaths are ByteString based, so this package only works on POSIX -- systems. For a more high-level version of this with proper Path type, -- use 'hpath-io', which makes use of this package. @package hpath-directory @version 0.13.0 module System.Posix.Foreign newtype DirType DirType :: Int -> DirType data Flags Flags :: Int -> Flags UnsupportedFlag :: String -> Flags unFlags :: Flags -> Int -- | Returns True if posix-paths was compiled with support for the -- provided flag. (As of this writing, the only flag for which this check -- may be necessary is oCloexec; all other flags will always yield -- True.) isSupported :: Flags -> Bool -- | O_CLOEXEC is not supported on every POSIX platform. Use -- isSupported oCloexec to determine if support for -- O_CLOEXEC was compiled into your version of posix-paths. (If -- not, using oCloexec will throw an exception.) oCloexec :: Flags dtBlk :: DirType oAppend :: Flags dtChr :: DirType pathMax :: Int oAsync :: Flags dtDir :: DirType oCreat :: Flags dtFifo :: DirType unionFlags :: [Flags] -> CInt dtLnk :: DirType oDirectory :: Flags oExcl :: Flags dtReg :: DirType oNoctty :: Flags dtSock :: DirType oNofollow :: Flags dtUnknown :: DirType oNonblock :: Flags oRdonly :: Flags oWronly :: Flags oRdwr :: Flags oSync :: Flags oTrunc :: Flags instance GHC.Show.Show System.Posix.Foreign.Flags instance GHC.Classes.Eq System.Posix.Foreign.Flags instance GHC.Show.Show System.Posix.Foreign.DirType instance GHC.Classes.Eq System.Posix.Foreign.DirType -- | Provides an alternative for openFd which gives us more control -- on what status flags to pass to the low-level open(2) call, -- in contrast to the unix package. module System.Posix.FD -- | Open and optionally create this file. See Files for information -- on how to use the FileMode type. -- -- Note that passing Just x as the 4th argument triggers the -- oCreat status flag, which must be set when you pass in -- oExcl to the status flags. Also see the manpage for -- open(2). openFd :: RawFilePath -> OpenMode -> [Flags] -> Maybe FileMode -> IO Fd -- | Provides error handling. module System.Posix.RawFilePath.Directory.Errors -- | Additional generic IO exceptions that the posix functions do not -- provide. data HPathIOException SameFile :: ByteString -> ByteString -> HPathIOException DestinationInSource :: ByteString -> ByteString -> HPathIOException RecursiveFailure :: [(RecursiveFailureHint, IOException)] -> HPathIOException -- | A type for giving failure hints on recursive failure, which allows to -- programmatically make choices without examining the weakly typed I/O -- error attributes (like ioeGetFileName). -- -- The first argument to the data constructor is always the source and -- the second the destination. data RecursiveFailureHint ReadContentsFailed :: ByteString -> ByteString -> RecursiveFailureHint CreateDirFailed :: ByteString -> ByteString -> RecursiveFailureHint CopyFileFailed :: ByteString -> ByteString -> RecursiveFailureHint RecreateSymlinkFailed :: ByteString -> ByteString -> RecursiveFailureHint isSameFile :: HPathIOException -> Bool isDestinationInSource :: HPathIOException -> Bool isRecursiveFailure :: HPathIOException -> Bool isReadContentsFailed :: RecursiveFailureHint -> Bool isCreateDirFailed :: RecursiveFailureHint -> Bool isCopyFileFailed :: RecursiveFailureHint -> Bool isRecreateSymlinkFailed :: RecursiveFailureHint -> Bool -- | Throws AlreadyExists IOError if file exists. throwFileDoesExist :: RawFilePath -> IO () -- | Throws AlreadyExists IOError if directory exists. throwDirDoesExist :: RawFilePath -> IO () -- | Uses isSameFile and throws SameFile if it returns True. throwSameFile :: RawFilePath -> RawFilePath -> IO () -- | Check if the files are the same by examining device and file id. This -- follows symbolic links. sameFile :: RawFilePath -> RawFilePath -> IO Bool -- | Checks whether the destination directory is contained within the -- source directory by comparing the device+file ID of the source -- directory with all device+file IDs of the parent directories of the -- destination. throwDestinationInSource :: RawFilePath -> RawFilePath -> IO () -- | Carries out an action, then checks if there is an IOException and a -- specific errno. If so, then it carries out another action, otherwise -- it rethrows the error. catchErrno :: [Errno] -> IO a -> IO a -> IO a -- | Execute the given action and retrow IO exceptions as a new Exception -- that have the given errno. If errno does not match the exception is -- rethrown as is. rethrowErrnoAs :: Exception e => [Errno] -> e -> IO a -> IO a -- | Like catchIOError, with arguments swapped. handleIOError :: (IOError -> IO a) -> IO a -> IO a hideError :: IOErrorType -> IO () -> IO () -- | Like bracket, but allows to have different clean-up actions -- depending on whether the in-between computation has raised an -- exception or not. bracketeer :: IO a -> (a -> IO b) -> (a -> IO b) -> (a -> IO c) -> IO c reactOnError :: IO a -> [(IOErrorType, IO a)] -> [(HPathIOException, IO a)] -> IO a instance GHC.Show.Show System.Posix.RawFilePath.Directory.Errors.HPathIOException instance GHC.Classes.Eq System.Posix.RawFilePath.Directory.Errors.HPathIOException instance GHC.Show.Show System.Posix.RawFilePath.Directory.Errors.RecursiveFailureHint instance GHC.Classes.Eq System.Posix.RawFilePath.Directory.Errors.RecursiveFailureHint instance GHC.Exception.Type.Exception System.Posix.RawFilePath.Directory.Errors.HPathIOException -- | Traversal and read operations on directories. module System.Posix.RawFilePath.Directory.Traversals -- | Gets all directory contents (not recursively). getDirectoryContents :: RawFilePath -> IO [(DirType, RawFilePath)] -- | Like getDirectoryContents except for a file descriptor. -- -- To avoid complicated error checks, the file descriptor is -- always closed, even if fdOpendir fails. Usually, this -- only happens on successful fdOpendir and after the directory -- stream is closed. Also see the manpage of fdopendir(3) for -- more details. getDirectoryContents' :: Fd -> IO [(DirType, RawFilePath)] -- | Get all files from a directory and its subdirectories. -- -- Upon entering a directory, allDirectoryContents will get all -- entries strictly. However the returned list is lazy in that -- directories will only be accessed on demand. -- -- Follows symbolic links for the input dir. allDirectoryContents :: RawFilePath -> IO [RawFilePath] -- | Get all files from a directory and its subdirectories strictly. -- -- Follows symbolic links for the input dir. allDirectoryContents' :: RawFilePath -> IO [RawFilePath] -- | Recursively apply the action to the parent directory and all -- files/subdirectories. -- -- This function allows for memory-efficient traversals. -- -- Follows symbolic links for the input dir. traverseDirectory :: (s -> RawFilePath -> IO s) -> s -> RawFilePath -> IO s readDirEnt :: DirStream -> IO (DirType, RawFilePath) packDirStream :: Ptr CDir -> DirStream unpackDirStream :: DirStream -> Ptr CDir -- | Binding to fdopendir(3). fdOpendir :: Fd -> IO DirStream -- | return the canonicalized absolute pathname -- -- like canonicalizePath, but uses realpath(3) realpath :: RawFilePath -> IO RawFilePath -- | This module provides IO related file operations like copy, delete, -- move and so on, similar to the directory package. -- -- 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. -- -- Import as: > import System.Posix.RawFilePath.Directory module System.Posix.RawFilePath.Directory data FileType Directory :: FileType RegularFile :: FileType SymbolicLink :: FileType BlockDevice :: FileType CharacterDevice :: FileType NamedPipe :: FileType Socket :: FileType -- | 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. data RecursiveErrorMode FailEarly :: RecursiveErrorMode CollectFailures :: RecursiveErrorMode -- | The mode for copy and file moves. Overwrite mode is usually not very -- well defined, but is a convenience shortcut. data CopyMode -- | fail if any target exists Strict :: CopyMode -- | overwrite targets Overwrite :: CopyMode -- | 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 exist
PermissionDenied if source directory can't be opened
SameFile 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 writable
InvalidArgument 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

-- -- Note: may call getcwd (only if destination is a relative -- path) copyDirRecursive :: RawFilePath -> RawFilePath -> CopyMode -> RecursiveErrorMode -> IO () -- | 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 -- to
PermissionDenied if source directory cannot be opened
SameFile 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
calls getcwd in Overwrite mode (if destination is a -- relative path)

recreateSymlink :: RawFilePath -> RawFilePath -> CopyMode -> IO () -- | 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 exist
NoSuchThing if source file is a a Socket
PermissionDenied if output directory is not writable
PermissionDenied if source directory can't be opened
InvalidArgument 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

-- -- Notes: -- --

may call getcwd in Overwrite mode (if destination is a -- relative path)

copyFile :: RawFilePath -> RawFilePath -> CopyMode -> IO () -- | 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

-- -- Note: may call getcwd in Overwrite mode (if destination is a -- relative path) easyCopy :: RawFilePath -> RawFilePath -> CopyMode -> RecursiveErrorMode -> IO () -- | 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 exist
PermissionDenied if the directory cannot be read

-- -- Notes: calls unlink deleteFile :: RawFilePath -> IO () -- | 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 exist
UnsatisfiedConstraints if directory is not empty
PermissionDenied if we can't open or write to parent -- directory

-- -- Notes: calls rmdir deleteDir :: RawFilePath -> IO () -- | 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 exist
PermissionDenied if we can't open or write to parent -- directory

deleteDirRecursive :: RawFilePath -> IO () -- | 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

easyDelete :: RawFilePath -> IO () -- | Opens a file appropriately by invoking xdg-open. The file type is not -- checked. This forks a process. openFile :: RawFilePath -> IO ProcessID -- | Executes a program with the given arguments. This forks a process. executeFile :: RawFilePath -> [ByteString] -> IO ProcessID -- | Create an empty regular file at the given directory with the given -- filename. -- -- Throws: -- --

PermissionDenied if output directory cannot be written -- to
AlreadyExists if destination already exists
NoSuchThing if any of the parent components of the path do -- not exist

createRegularFile :: FileMode -> RawFilePath -> IO () -- | Create an empty directory at the given directory with the given -- filename. -- -- Throws: -- --

PermissionDenied if output directory cannot be written -- to
AlreadyExists if destination already exists
NoSuchThing if any of the parent components of the path do -- not exist

createDir :: FileMode -> RawFilePath -> IO () -- | Create an empty directory at the given directory with the given -- filename. -- -- Throws: -- --

PermissionDenied if output directory cannot be written -- to
NoSuchThing if any of the parent components of the path do -- not exist

createDirIfMissing :: FileMode -> RawFilePath -> IO () -- | 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 to
AlreadyExists if destination already exists and is *not* a -- directory

-- -- Note: calls getcwd if the input path is a relative path createDirRecursive :: FileMode -> RawFilePath -> IO () -- | Create a symlink. -- -- Throws: -- --

PermissionDenied if output directory cannot be written -- to
AlreadyExists if destination file already exists
NoSuchThing if any of the parent components of the path do -- not exist

-- -- Note: calls symlink createSymlink :: RawFilePath -> RawFilePath -> IO () -- | 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 exist
PermissionDenied if output directory cannot be written -- to
PermissionDenied if source directory cannot be opened
UnsupportedOperation if source and destination are on -- different devices
AlreadyExists if destination already exists
SameFile if destination and source are the same file -- (HPathIOException)

-- -- Note: calls rename (but does not allow to rename over existing -- files) renameFile :: RawFilePath -> RawFilePath -> IO () -- | 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 and easyDelete as -- a fallback to renameFile, file types that are not -- RegularFile, SymbolicLink or Directory may be -- ignored
for Overwrite mode, the destination will be deleted (not -- recursively) before moving

-- -- Throws: -- --

NoSuchThing if source file does not exist
PermissionDenied if output directory cannot be written -- to
PermissionDenied if source directory cannot be opened
SameFile 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)
calls getcwd in Overwrite mode if destination is a -- relative path

moveFile :: RawFilePath -> RawFilePath -> CopyMode -> IO () -- | Read the given file *at once* into memory as a lazy ByteString. -- Symbolic links are followed, no sanity checks on file size or file -- type. File must exist. Uses Builders under the hood (hence lazy -- ByteString). -- -- Safety/reliability concerns: -- --

the whole file is read into memory, this doesn't read lazily

-- -- Throws: -- --

InappropriateType if file is not a regular file or a -- symlink
PermissionDenied if we cannot read the file or the -- directory containting it
NoSuchThing if the file does not exist

readFile :: RawFilePath -> IO ByteString -- | Open the given file as a filestream. Once the filestream exits, the -- filehandle is cleaned up. -- -- Throws: -- --

InappropriateType if file is not a regular file or a -- symlink
PermissionDenied if we cannot read the file or the -- directory containting it
NoSuchThing if the file does not exist

readFileStream :: RawFilePath -> IO (SerialT IO ByteString) -- | Write a given ByteString to a file, truncating the file beforehand. -- Follows symlinks. -- -- Throws: -- --

InappropriateType if file is not a regular file or a -- symlink
PermissionDenied if we cannot read the file or the -- directory containting it
NoSuchThing if the file does not exist

writeFile :: RawFilePath -> Maybe FileMode -> 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 -- symlink
PermissionDenied if we cannot read the file or the -- directory containting it
NoSuchThing if the file does not exist

-- -- Note: uses streamly under the hood writeFileL :: RawFilePath -> Maybe FileMode -> ByteString -> IO () -- | Append a given ByteString to a file. The file must exist. Follows -- symlinks. -- -- Throws: -- --

InappropriateType if file is not a regular file or a -- symlink
PermissionDenied if we cannot read the file or the -- directory containting it
NoSuchThing if the file does not exist

appendFile :: RawFilePath -> ByteString -> IO () -- | Default permissions for a new file. newFilePerms :: FileMode -- | Default permissions for a new directory. newDirPerms :: FileMode -- | Checks if the given file exists. Does not follow symlinks. -- -- Only eNOENT is catched (and returns False). doesExist :: RawFilePath -> IO Bool -- | Checks if the given file exists and is not a directory. Does not -- follow symlinks. -- -- Only eNOENT is catched (and returns False). doesFileExist :: RawFilePath -> IO Bool -- | Checks if the given file exists and is a directory. Does not follow -- symlinks. -- -- Only eNOENT is catched (and returns False). doesDirectoryExist :: RawFilePath -> IO Bool -- | 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

isReadable :: RawFilePath -> IO Bool -- | 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

isWritable :: RawFilePath -> IO Bool -- | 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

isExecutable :: RawFilePath -> IO Bool -- | Checks whether the directory at the given path exists and can be -- opened. This invokes openDirStream which follows symlinks. canOpenDirectory :: RawFilePath -> IO Bool getModificationTime :: RawFilePath -> IO UTCTime setModificationTime :: RawFilePath -> EpochTime -> IO () setModificationTimeHiRes :: RawFilePath -> POSIXTime -> IO () -- | 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 exist
InappropriateType 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 opened

getDirsFiles :: RawFilePath -> IO [RawFilePath] -- | Like getDirsFiles, but returns the filename only, instead of -- prepending the base path. getDirsFiles' :: RawFilePath -> IO [RawFilePath] -- | Get the file type of the file located at the given path. Does not -- follow symbolic links. -- -- Throws: -- --

NoSuchThing if the file does not exist
PermissionDenied if any part of the path is not -- accessible

getFileType :: RawFilePath -> IO FileType -- | Applies realpath on the given path. -- -- Throws: -- --

NoSuchThing if the file at the given path does not -- exist
NoSuchThing if the symlink is broken

canonicalizePath :: RawFilePath -> IO RawFilePath -- | 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

toAbs :: RawFilePath -> IO RawFilePath instance GHC.Show.Show System.Posix.RawFilePath.Directory.FileType instance GHC.Classes.Eq System.Posix.RawFilePath.Directory.FileType