hpath/HPath-IO.html
travis-ci f5f0f514c6 Lastest docs updated
travis build: 55
commit: 2d96311b33
auto-pushed to gh-pages
2016-06-01 17:01:34 +00:00

59 lines
42 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.7.3: Support for well-typed paths</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Copyright</th><td>&#169; 2016 Julian Ospald</td></tr><tr><th>License</th><td>GPL-2</td></tr><tr><th>Maintainer</th><td>Julian Ospald &lt;hasufell@posteo.de&gt;</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"><a href="#v:copyDirRecursive">copyDirRecursive</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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:copyDirRecursiveOverwrite">copyDirRecursiveOverwrite</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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:copyFileOverwrite">copyFileOverwrite</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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:easyCopyOverwrite">easyCopyOverwrite</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; [<a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a>] -&gt; <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="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <a href="https://hackage.haskell.org/package/bytestring-0.10.4.0/docs/Data-ByteString.html#t:ByteString">ByteString</a> -&gt; <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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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:moveFileOverwrite">moveFileOverwrite</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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">&nbsp;</td></tr><tr><td class="src"><a name="v:RegularFile" class="def">RegularFile</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a name="v:SymbolicLink" class="def">SymbolicLink</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a name="v:BlockDevice" class="def">BlockDevice</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a name="v:CharacterDevice" class="def">CharacterDevice</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a name="v:NamedPipe" class="def">NamedPipe</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a name="v:Socket" class="def">Socket</a></td><td class="doc empty">&nbsp;</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">&nbsp;</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">&nbsp;</td></tr></table></div></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>source dir</p></td></tr><tr><td class="src">-&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>full destination</p></td></tr><tr><td class="src">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Copies a directory recursively to the given destination.
Does not follow symbolic links.</p><p>For directory contents, this has the same behavior as <code><a href="HPath-IO.html#v:easyCopy">easyCopy</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><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 output directory is not writable</li><li><code>PermissionDenied</code> if source directory can't be opened</li><li><code>InvalidArgument</code> if source directory is wrong type (symlink)</li><li><code>InvalidArgument</code> if source directory is wrong type (regular file)</li><li><code>AlreadyExists</code> if destination already exists</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></div></div><div class="top"><p class="src"><a name="v:copyDirRecursiveOverwrite" class="def">copyDirRecursiveOverwrite</a> <a href="src/HPath-IO.html#copyDirRecursiveOverwrite" 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 dir</p></td></tr><tr><td class="src">-&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a></td><td class="doc"><p>full destination</p></td></tr><tr><td class="src">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Like <code><a href="HPath-IO.html#v:copyDirRecursive">copyDirRecursive</a></code> except it overwrites contents of directories
if any.</p><p>For directory contents, this has the same behavior as <code><a href="HPath-IO.html#v:easyCopyOverwrite">easyCopyOverwrite</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>Throws:</p><ul><li><code>NoSuchThing</code> if source directory does not exist</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 directory is wrong type (symlink)</li><li><code>InvalidArgument</code> if source directory is wrong type (regular file)</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></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">-&gt; <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">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Recreate a symlink.</p><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>AlreadyExists</code> if destination file already exists</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>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">-&gt; <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">-&gt; <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">&nbsp;</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 &quot;copying&quot; 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>Safety/reliability concerns:</p><ul><li>when used on <code><a href="HPath-IO.html#v:CharacterDevice">CharacterDevice</a></code>, reads the &quot;contents&quot; 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 &quot;contents&quot;
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>AlreadyExists</code> if destination already exists</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>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:copyFileOverwrite" class="def">copyFileOverwrite</a> <a href="src/HPath-IO.html#copyFileOverwrite" 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">-&gt; <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">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Like <code><a href="HPath-IO.html#v:copyFile">copyFile</a></code> except it overwrites the destination if it already
exists.</p><p>Safety/reliability concerns:</p><ul><li>when used on <code><a href="HPath-IO.html#v:CharacterDevice">CharacterDevice</a></code>, reads the &quot;contents&quot; 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 &quot;contents&quot;
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><li>not atomic, since it uses read/write</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 <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>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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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><div class="top"><p class="src"><a name="v:easyCopyOverwrite" class="def">easyCopyOverwrite</a> :: <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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#easyCopyOverwrite" class="link">Source</a></p><div class="doc"><p>Like <code><a href="HPath-IO.html#v:easyCopy">easyCopy</a></code> except it overwrites the destination if it already exists.
For directories, this overwrites contents without pruning them, so the resulting
directory may have more files than have been copied.</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> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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> -&gt; <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">-&gt; [<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">-&gt; <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">&nbsp;</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="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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">-&gt; <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">-&gt; <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">&nbsp;</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> -&gt; <a href="HPath.html#t:Path">Path</a> <a href="HPath.html#t:Abs">Abs</a> -&gt; <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">-&gt; <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">-&gt; <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">&nbsp;</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>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></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: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:moveFileOverwrite" class="def">moveFileOverwrite</a> <a href="src/HPath-IO.html#moveFileOverwrite" 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">-&gt; <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">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Like <code><a href="HPath-IO.html#v:moveFile">moveFile</a></code>, but overwrites the destination if it exists.</p><p>Does not follow symbolic links, but renames the symbolic link file.</p><p>Ignores 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>copy-delete fallback is inherently non-atomic</li><li>checks for file types and destination file existence explicitly</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>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">-&gt; <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">&nbsp;</td></tr></table></div><div class="doc"><p>Gets all filenames of the given directory. This excludes &quot;.&quot; and &quot;..&quot;.
This version does not follow symbolic links.</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> -&gt; <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> -&gt; <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>