74 lines
40 KiB
HTML
74 lines
40 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>HPath.IO</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
|
|
window.onload = function () {pageLoad();setSynopsis("mini_HPath-IO.html");};
|
|
//]]>
|
|
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/HPath-IO.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">hpath-0.8.0: Support for well-typed paths</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Copyright</th><td>© 2016 Julian Ospald</td></tr><tr><th>License</th><td>BSD3</td></tr><tr><th>Maintainer</th><td>Julian Ospald <hasufell@posteo.de></td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell2010</td></tr></table><p class="caption">HPath.IO</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Types</a></li><li><a href="#g:2">File copying</a></li><li><a href="#g:3">File deletion</a></li><li><a href="#g:4">File opening</a></li><li><a href="#g:5">File creation</a></li><li><a href="#g:6">File renaming/moving</a></li><li><a href="#g:7">File permissions</a></li><li><a href="#g:8">Directory reading</a></li><li><a href="#g:9">Filetype operations</a></li><li><a href="#g:10">Others</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This module provides high-level IO related file operations like
|
|
copy, delete, move and so on. It only operates on <em>Path Abs</em> which
|
|
guarantees us well-typed paths which are absolute.</p><p>Some functions are just path-safe wrappers around
|
|
unix functions, others have stricter exception handling
|
|
and some implement functionality that doesn't have a unix
|
|
counterpart (like <code><a href="HPath-IO.html#v:copyDirRecursive">copyDirRecursive</a></code>).</p><p>Some of these operations are due to their nature <strong>not atomic</strong>, 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.</p><p>Note: <code><a href="HPath-IO.html#v:BlockDevice">BlockDevice</a></code>, <code><a href="HPath-IO.html#v:CharacterDevice">CharacterDevice</a></code>, <code><a href="HPath-IO.html#v:NamedPipe">NamedPipe</a></code> and <code><a href="HPath-IO.html#v:Socket">Socket</a></code>
|
|
are ignored by some of the more high-level functions (like <code><a href="HPath-IO.html#v:easyCopy">easyCopy</a></code>).
|
|
For other functions (like <code><a href="HPath-IO.html#v:copyFile">copyFile</a></code>), the behavior on these file types is
|
|
unreliable/unsafe. Check the documentation of those functions for details.</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">data</span> <a href="#t:FileType">FileType</a><ul class="subs"><li>= <a href="#v:Directory">Directory</a></li><li>| <a href="#v:RegularFile">RegularFile</a></li><li>| <a href="#v:SymbolicLink">SymbolicLink</a></li><li>| <a href="#v:BlockDevice">BlockDevice</a></li><li>| <a href="#v:CharacterDevice">CharacterDevice</a></li><li>| <a href="#v:NamedPipe">NamedPipe</a></li><li>| <a href="#v:Socket">Socket</a></li></ul></li><li class="src short"><span class="keyword">data</span> <a href="#t:RecursiveErrorMode">RecursiveErrorMode</a><ul class="subs"><li>= <a href="#v:FailEarly">FailEarly</a></li><li>| <a href="#v:CollectFailures">CollectFailures</a></li></ul></li><li class="src short"><span class="keyword">data</span> <a href="#t:CopyMode">CopyMode</a><ul class="subs"><li>= <a href="#v:Strict">Strict</a></li><li>| <a href="#v:Overwrite">Overwrite</a></li></ul></li><li class="src short"><a href="#v:copyDirRecursive">copyDirRecursive</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="HPath-IO.html#t:RecursiveErrorMode">RecursiveErrorMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:recreateSymlink">recreateSymlink</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:copyFile">copyFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:easyCopy">easyCopy</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="HPath-IO.html#t:RecursiveErrorMode">RecursiveErrorMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:deleteFile">deleteFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:deleteDir">deleteDir</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:deleteDirRecursive">deleteDirRecursive</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:easyDelete">easyDelete</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:openFile">openFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:ProcessID">ProcessID</a></li><li class="src short"><a href="#v:executeFile">executeFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> [<a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a>] -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:ProcessID">ProcessID</a></li><li class="src short"><a href="#v:createRegularFile">createRegularFile</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:createDir">createDir</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:createSymlink">createSymlink</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:renameFile">renameFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:moveFile">moveFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:newFilePerms">newFilePerms</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a></li><li class="src short"><a href="#v:newDirPerms">newDirPerms</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a></li><li class="src short"><a href="#v:getDirsFiles">getDirsFiles</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> [<a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a>]</li><li class="src short"><a href="#v:getFileType">getFileType</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="HPath-IO.html#t:FileType">FileType</a></li><li class="src short"><a href="#v:canonicalizePath">canonicalizePath</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> (<a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a>)</li></ul></div><div id="interface"><h1 id="g:1">Types</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:FileType" class="def">FileType</a> <a href="src/HPath-IO.html#FileType" class="link">Source</a></p><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:Directory" class="def">Directory</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:RegularFile" class="def">RegularFile</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:SymbolicLink" class="def">SymbolicLink</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:BlockDevice" class="def">BlockDevice</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:CharacterDevice" class="def">CharacterDevice</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:NamedPipe" class="def">NamedPipe</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Socket" class="def">Socket</a></td><td class="doc empty"> </td></tr></table></div><div class="subs instances"><p id="control.i:FileType" class="caption collapser" onclick="toggleSection('i:FileType')">Instances</p><div id="section.i:FileType" class="show"><table><tr><td class="src"><a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Eq.html#t:Eq">Eq</a> <a href="HPath-IO.html#t:FileType">FileType</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/Text-Show.html#t:Show">Show</a> <a href="HPath-IO.html#t:FileType">FileType</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:RecursiveErrorMode" class="def">RecursiveErrorMode</a> <a href="src/HPath-IO.html#RecursiveErrorMode" class="link">Source</a></p><div class="doc"><p>The error mode for any recursive operation.</p><p>On <code><a href="HPath-IO.html#v:FailEarly">FailEarly</a></code> the whole operation fails immediately if any of the
|
|
recursive sub-operations fail, which is sort of the default
|
|
for IO operations.</p><p>On <code><a href="HPath-IO.html#v:CollectFailures">CollectFailures</a></code> skips errors in the recursion and keeps on recursing.
|
|
However all errors are collected in the <code><a href="HPath-IO-Errors.html#v:RecursiveFailure">RecursiveFailure</a></code> error type,
|
|
which is raised finally if there was any error.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:FailEarly" class="def">FailEarly</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:CollectFailures" class="def">CollectFailures</a></td><td class="doc empty"> </td></tr></table></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:CopyMode" class="def">CopyMode</a> <a href="src/HPath-IO.html#CopyMode" class="link">Source</a></p><div class="doc"><p>The mode for copy and file moves.
|
|
Overwrite mode is usually not very well defined, but is a convenience
|
|
shortcut.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:Strict" class="def">Strict</a></td><td class="doc"><p>fail if any target exists</p></td></tr><tr><td class="src"><a name="v:Overwrite" class="def">Overwrite</a></td><td class="doc"><p>overwrite targets</p></td></tr></table></div></div><h1 id="g:2">File copying</h1><div class="top"><p class="src"><a name="v:copyDirRecursive" class="def">copyDirRecursive</a> <a href="src/HPath-IO.html#copyDirRecursive" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>copy contents of this source dir</p></td></tr><tr><td class="src">-> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>to this full destination (parent dirs
|
|
are not automatically created)</p></td></tr><tr><td class="src">-> <a href="HPath-IO.html#t:CopyMode">CopyMode</a></td><td class="doc empty"> </td></tr><tr><td class="src">-> <a href="HPath-IO.html#t:RecursiveErrorMode">RecursiveErrorMode</a></td><td class="doc empty"> </td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Copies the contents of a directory recursively to the given destination.
|
|
Does not follow symbolic links. This behaves more or less like:</p><pre> mkdir /destination/dir
|
|
cp -R /source/dir/* /destination/dir/
|
|
</pre><p>For directory contents, this will ignore any file type that is not
|
|
<code><a href="HPath-IO.html#v:RegularFile">RegularFile</a></code>, <code><a href="HPath-IO.html#v:SymbolicLink">SymbolicLink</a></code> or <code><a href="HPath-IO.html#v:Directory">Directory</a></code>.</p><p>For <code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> 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.</p><p>Note that there is no guaranteed ordering of the exceptions
|
|
contained within <code><a href="HPath-IO-Errors.html#v:RecursiveFailure">RecursiveFailure</a></code> in <code><a href="HPath-IO.html#v:CollectFailures">CollectFailures</a></code> RecursiveErrorMode.</p><p>Safety/reliability concerns:</p><ul><li>not atomic</li><li>examines filetypes explicitly</li><li>an explicit check <code><a href="HPath-IO-Errors.html#v:throwDestinationInSource">throwDestinationInSource</a></code> 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)</li></ul><p>Throws:</p><ul><li><code>NoSuchThing</code> if source directory does not exist</li><li><code>PermissionDenied</code> if source directory can't be opened</li><li><code><a href="HPath-IO-Errors.html#v:SameFile">SameFile</a></code> if source and destination are the same file
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li><li><code><a href="HPath-IO-Errors.html#v:DestinationInSource">DestinationInSource</a></code> if destination is contained in source
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:FailEarly">FailEarly</a></code> RecursiveErrorMode only:</p><ul><li><code>PermissionDenied</code> if output directory is not writable</li><li><code>InvalidArgument</code> if source directory is wrong type (symlink)</li><li><code>InappropriateType</code> if source directory is wrong type (regular file)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:CollectFailures">CollectFailures</a></code> RecursiveErrorMode only:</p><ul><li><code><a href="HPath-IO-Errors.html#v:RecursiveFailure">RecursiveFailure</a></code> if any of the recursive operations that are not
|
|
part of the top-directory sanity-checks fail (<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:Strict">Strict</a></code> CopyMode only:</p><ul><li><code>AlreadyExists</code> if destination already exists</li></ul></div></div><div class="top"><p class="src"><a name="v:recreateSymlink" class="def">recreateSymlink</a> <a href="src/HPath-IO.html#recreateSymlink" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>the old symlink file</p></td></tr><tr><td class="src">-> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>destination file</p></td></tr><tr><td class="src">-> <a href="HPath-IO.html#t:CopyMode">CopyMode</a></td><td class="doc empty"> </td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Recreate a symlink.</p><p>In <code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> copy mode only files and empty directories are deleted.</p><p>Safety/reliability concerns:</p><ul><li><code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> mode is inherently non-atomic</li></ul><p>Throws:</p><ul><li><code>InvalidArgument</code> if source file is wrong type (not a symlink)</li><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>PermissionDenied</code> if source directory cannot be opened</li><li><code><a href="HPath-IO-Errors.html#v:SameFile">SameFile</a></code> if source and destination are the same file
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:Strict">Strict</a></code> mode only:</p><ul><li><code>AlreadyExists</code> if destination file already exists</li></ul><p>Throws in <code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> mode only:</p><ul><li><code>UnsatisfiedConstraints</code> if destination file is non-empty directory</li></ul><p>Note: calls <code>symlink</code></p></div></div><div class="top"><p class="src"><a name="v:copyFile" class="def">copyFile</a> <a href="src/HPath-IO.html#copyFile" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>source file</p></td></tr><tr><td class="src">-> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>destination file</p></td></tr><tr><td class="src">-> <a href="HPath-IO.html#t:CopyMode">CopyMode</a></td><td class="doc empty"> </td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Copies the given regular file to the given destination.
|
|
Neither follows symbolic links, nor accepts them.
|
|
For "copying" symbolic links, use <code><a href="HPath-IO.html#v:recreateSymlink">recreateSymlink</a></code> instead.</p><p>Note that this is still sort of a low-level function and doesn't
|
|
examine file types. For a more high-level version, use <code><a href="HPath-IO.html#v:easyCopy">easyCopy</a></code>
|
|
instead.</p><p>In <code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> copy mode only overwrites actual files, not directories.</p><p>Safety/reliability concerns:</p><ul><li><code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> mode is not atomic</li><li>when used on <code><a href="HPath-IO.html#v:CharacterDevice">CharacterDevice</a></code>, reads the "contents" and copies
|
|
them to a regular file, which might take indefinitely</li><li>when used on <code><a href="HPath-IO.html#v:BlockDevice">BlockDevice</a></code>, may either read the "contents"
|
|
and copy them to a regular file (potentially hanging indefinitely)
|
|
or may create a regular empty destination file</li><li>when used on <code><a href="HPath-IO.html#v:NamedPipe">NamedPipe</a></code>, will hang indefinitely</li></ul><p>Throws:</p><ul><li><code>NoSuchThing</code> if source file does not exist</li><li><code>NoSuchThing</code> if source file is a a <code><a href="HPath-IO.html#v:Socket">Socket</a></code></li><li><code>PermissionDenied</code> if output directory is not writable</li><li><code>PermissionDenied</code> if source directory can't be opened</li><li><code>InvalidArgument</code> if source file is wrong type (symlink or directory)</li><li><code><a href="HPath-IO-Errors.html#v:SameFile">SameFile</a></code> if source and destination are the same file
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:Strict">Strict</a></code> mode only:</p><ul><li><code>AlreadyExists</code> if destination already exists</li></ul><p>Note: calls <code>sendfile</code> and possibly <code><a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/Text-Read.html#v:read">read</a></code>/<code>write</code> as fallback</p></div></div><div class="top"><p class="src"><a name="v:easyCopy" class="def">easyCopy</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath-IO.html#t:CopyMode">CopyMode</a> -> <a href="HPath-IO.html#t:RecursiveErrorMode">RecursiveErrorMode</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#easyCopy" class="link">Source</a></p><div class="doc"><p>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.</p><p>Safety/reliability concerns:</p><ul><li>examines filetypes explicitly</li><li>calls <code><a href="HPath-IO.html#v:copyDirRecursive">copyDirRecursive</a></code> for directories</li></ul></div></div><h1 id="g:3">File deletion</h1><div class="top"><p class="src"><a name="v:deleteFile" class="def">deleteFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#deleteFile" class="link">Source</a></p><div class="doc"><p>Deletes the given file. Raises <code>eISDIR</code>
|
|
if run on a directory. Does not follow symbolic links.</p><p>Throws:</p><ul><li><code>InappropriateType</code> for wrong file type (directory)</li><li><code>NoSuchThing</code> if the file does not exist</li><li><code>PermissionDenied</code> if the directory cannot be read</li></ul></div></div><div class="top"><p class="src"><a name="v:deleteDir" class="def">deleteDir</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#deleteDir" class="link">Source</a></p><div class="doc"><p>Deletes the given directory, which must be empty, never symlinks.</p><p>Throws:</p><ul><li><code>InappropriateType</code> for wrong file type (symlink to directory)</li><li><code>InappropriateType</code> for wrong file type (regular file)</li><li><code>NoSuchThing</code> if directory does not exist</li><li><code>UnsatisfiedConstraints</code> if directory is not empty</li><li><code>PermissionDenied</code> if we can't open or write to parent directory</li></ul><p>Notes: calls <code>rmdir</code></p></div></div><div class="top"><p class="src"><a name="v:deleteDirRecursive" class="def">deleteDirRecursive</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#deleteDirRecursive" class="link">Source</a></p><div class="doc"><p>Deletes the given directory recursively. Does not follow symbolic
|
|
links. Tries <code><a href="HPath-IO.html#v:deleteDir">deleteDir</a></code> first before attemtping a recursive
|
|
deletion.</p><p>On directory contents this behaves like <code><a href="HPath-IO.html#v:easyDelete">easyDelete</a></code>
|
|
and thus will ignore any file type that is not <code><a href="HPath-IO.html#v:RegularFile">RegularFile</a></code>,
|
|
<code><a href="HPath-IO.html#v:SymbolicLink">SymbolicLink</a></code> or <code><a href="HPath-IO.html#v:Directory">Directory</a></code>.</p><p>Safety/reliability concerns:</p><ul><li>not atomic</li><li>examines filetypes explicitly</li></ul><p>Throws:</p><ul><li><code>InappropriateType</code> for wrong file type (symlink to directory)</li><li><code>InappropriateType</code> for wrong file type (regular file)</li><li><code>NoSuchThing</code> if directory does not exist</li><li><code>PermissionDenied</code> if we can't open or write to parent directory</li></ul></div></div><div class="top"><p class="src"><a name="v:easyDelete" class="def">easyDelete</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#easyDelete" class="link">Source</a></p><div class="doc"><p>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.</p><p>Safety/reliability concerns:</p><ul><li>examines filetypes explicitly</li><li>calls <code><a href="HPath-IO.html#v:deleteDirRecursive">deleteDirRecursive</a></code> for directories</li></ul></div></div><h1 id="g:4">File opening</h1><div class="top"><p class="src"><a name="v:openFile" class="def">openFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:ProcessID">ProcessID</a> <a href="src/HPath-IO.html#openFile" class="link">Source</a></p><div class="doc"><p>Opens a file appropriately by invoking xdg-open. The file type
|
|
is not checked. This forks a process.</p></div></div><div class="top"><p class="src"><a name="v:executeFile" class="def">executeFile</a> <a href="src/HPath-IO.html#executeFile" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>program</p></td></tr><tr><td class="src">-> [<a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a>]</td><td class="doc"><p>arguments</p></td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:ProcessID">ProcessID</a></td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Executes a program with the given arguments. This forks a process.</p></div></div><h1 id="g:5">File creation</h1><div class="top"><p class="src"><a name="v:createRegularFile" class="def">createRegularFile</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#createRegularFile" class="link">Source</a></p><div class="doc"><p>Create an empty regular file at the given directory with the given
|
|
filename.</p><p>Throws:</p><ul><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>AlreadyExists</code> if destination file already exists</li></ul></div></div><div class="top"><p class="src"><a name="v:createDir" class="def">createDir</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#createDir" class="link">Source</a></p><div class="doc"><p>Create an empty directory at the given directory with the given filename.</p><p>Throws:</p><ul><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>AlreadyExists</code> if destination directory already exists</li></ul></div></div><div class="top"><p class="src"><a name="v:createSymlink" class="def">createSymlink</a> <a href="src/HPath-IO.html#createSymlink" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>destination file</p></td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>path the symlink points to</p></td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Create a symlink.</p><p>Throws:</p><ul><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>AlreadyExists</code> if destination file already exists</li></ul><p>Note: calls <code>symlink</code></p></div></div><h1 id="g:6">File renaming/moving</h1><div class="top"><p class="src"><a name="v:renameFile" class="def">renameFile</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> () <a href="src/HPath-IO.html#renameFile" class="link">Source</a></p><div class="doc"><p>Rename a given file with the provided filename. Destination and source
|
|
must be on the same device, otherwise <code><a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/Foreign-C-Error.html#v:eXDEV">eXDEV</a></code> will be raised.</p><p>Does not follow symbolic links, but renames the symbolic link file.</p><p>Safety/reliability concerns:</p><ul><li>has a separate set of exception handling, apart from the syscall</li></ul><p>Throws:</p><ul><li><code>NoSuchThing</code> if source file does not exist</li><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>PermissionDenied</code> if source directory cannot be opened</li><li><code>UnsupportedOperation</code> if source and destination are on different
|
|
devices</li><li><code><a href="HPath-IO-Errors.html#v:FileDoesExist">FileDoesExist</a></code> if destination file already exists
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li><li><code><a href="HPath-IO-Errors.html#v:DirDoesExist">DirDoesExist</a></code> if destination directory already exists
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li><li><code><a href="HPath-IO-Errors.html#v:SameFile">SameFile</a></code> if destination and source are the same file
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Note: calls <code><a href="https://hackage.haskell.org/package/unix-2.7.0.1/docs/System-Posix-Files-ByteString.html#v:rename">rename</a></code> (but does not allow to rename over existing files)</p></div></div><div class="top"><p class="src"><a name="v:moveFile" class="def">moveFile</a> <a href="src/HPath-IO.html#moveFile" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>file to move</p></td></tr><tr><td class="src">-> <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>destination</p></td></tr><tr><td class="src">-> <a href="HPath-IO.html#t:CopyMode">CopyMode</a></td><td class="doc empty"> </td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Move a file. This also works across devices by copy-delete fallback.
|
|
And also works on directories.</p><p>Does not follow symbolic links, but renames the symbolic link file.</p><p>Safety/reliability concerns:</p><ul><li><code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> mode is not atomic</li><li>copy-delete fallback is inherently non-atomic</li><li>since this function calls <code><a href="HPath-IO.html#v:easyCopy">easyCopy</a></code> and <code><a href="HPath-IO.html#v:easyDelete">easyDelete</a></code> as a fallback
|
|
to <code><a href="HPath-IO.html#v:renameFile">renameFile</a></code>, file types that are not <code><a href="HPath-IO.html#v:RegularFile">RegularFile</a></code>, <code><a href="HPath-IO.html#v:SymbolicLink">SymbolicLink</a></code>
|
|
or <code><a href="HPath-IO.html#v:Directory">Directory</a></code> may be ignored</li><li>for <code><a href="HPath-IO.html#v:Overwrite">Overwrite</a></code> mode, the destination will be deleted (not recursively)
|
|
before moving</li></ul><p>Throws:</p><ul><li><code>NoSuchThing</code> if source file does not exist</li><li><code>PermissionDenied</code> if output directory cannot be written to</li><li><code>PermissionDenied</code> if source directory cannot be opened</li><li><code><a href="HPath-IO-Errors.html#v:SameFile">SameFile</a></code> if destination and source are the same file
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Throws in <code><a href="HPath-IO.html#v:Strict">Strict</a></code> mode only:</p><ul><li><code><a href="HPath-IO-Errors.html#v:FileDoesExist">FileDoesExist</a></code> if destination file already exists (<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li><li><code><a href="HPath-IO-Errors.html#v:DirDoesExist">DirDoesExist</a></code> if destination directory already exists
|
|
(<code><a href="HPath-IO-Errors.html#t:HPathIOException">HPathIOException</a></code>)</li></ul><p>Note: calls <code><a href="https://hackage.haskell.org/package/unix-2.7.0.1/docs/System-Posix-Files-ByteString.html#v:rename">rename</a></code> (but does not allow to rename over existing files)</p></div></div><h1 id="g:7">File permissions</h1><div class="top"><p class="src"><a name="v:newFilePerms" class="def">newFilePerms</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> <a href="src/HPath-IO.html#newFilePerms" class="link">Source</a></p><div class="doc"><p>Default permissions for a new file.</p></div></div><div class="top"><p class="src"><a name="v:newDirPerms" class="def">newDirPerms</a> :: <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-Posix-Types.html#t:FileMode">FileMode</a> <a href="src/HPath-IO.html#newDirPerms" class="link">Source</a></p><div class="doc"><p>Default permissions for a new directory.</p></div></div><h1 id="g:8">Directory reading</h1><div class="top"><p class="src"><a name="v:getDirsFiles" class="def">getDirsFiles</a> <a href="src/HPath-IO.html#getDirsFiles" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>dir to read</p></td></tr><tr><td class="src">-> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> [<a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a>]</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Gets all filenames of the given directory. This excludes "." and "..".
|
|
This version does not follow symbolic links.</p><p>The contents are not sorted and there is no guarantee on the ordering.</p><p>Throws:</p><ul><li><code>NoSuchThing</code> if directory does not exist</li><li><code>InappropriateType</code> if file type is wrong (file)</li><li><code>InappropriateType</code> if file type is wrong (symlink to file)</li><li><code>InappropriateType</code> if file type is wrong (symlink to dir)</li><li><code>PermissionDenied</code> if directory cannot be opened</li></ul></div></div><h1 id="g:9">Filetype operations</h1><div class="top"><p class="src"><a name="v:getFileType" class="def">getFileType</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> <a href="HPath-IO.html#t:FileType">FileType</a> <a href="src/HPath-IO.html#getFileType" class="link">Source</a></p><div class="doc"><p>Get the file type of the file located at the given path. Does
|
|
not follow symbolic links.</p><p>Throws:</p><ul><li><code>NoSuchThing</code> if the file does not exist</li><li><code>PermissionDenied</code> if any part of the path is not accessible</li></ul></div></div><h1 id="g:10">Others</h1><div class="top"><p class="src"><a name="v:canonicalizePath" class="def">canonicalizePath</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -> <a href="https://hackage.haskell.org/package/base-4.7.0.2/docs/System-IO.html#t:IO">IO</a> (<a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a>) <a href="src/HPath-IO.html#canonicalizePath" class="link">Source</a></p><div class="doc"><p>Applies <code>realpath</code> on the given absolute path.</p><p>Throws:</p><ul><li><code>NoSuchThing</code> if the file at the given path does not exist</li><li><code>NoSuchThing</code> if the symlink is broken</li></ul></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.14.3</p></div></body></html> |