-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Platform-agnostic library for filesystem operations
°5u
°5uThis library provides a basic set of operations for manipulating files
°5uand directories in a portable way.
@package directory
@version 1.3.1.5


-- | Internal modules are always subject to change from version to version.
module System.Directory.Internal.Prelude

-- | Uninhabited data type
data Void

-- | A mirror image of <a>first</a>.
°5u
°5uThe default definition may be overridden with a more efficient version
°5uif desired.
second :: Arrow a => a b c -> a (d, b) (d, c)

-- | <a>killThread</a> raises the <a>ThreadKilled</a> exception in the
°5ugiven thread (GHC only).
°5u
°5u<pre>
°5ukillThread tid = throwTo tid ThreadKilled
°5u</pre>
killThread :: ThreadId -> IO ()

-- | Creates a new thread to run the <a>IO</a> computation passed as the
°5ufirst argument, and returns the <a>ThreadId</a> of the newly created
°5uthread.
°5u
°5uThe new thread will be a lightweight, <i>unbound</i> thread. Foreign
°5ucalls made by this thread are not guaranteed to be made by any
°5uparticular OS thread; if you need foreign calls to be made by a
°5uparticular OS thread, then use <a>forkOS</a> instead.
°5u
°5uThe new thread inherits the <i>masked</i> state of the parent (see
°5u<a>mask</a>).
°5u
°5uThe newly created thread has an exception handler that discards the
°5uexceptions <a>BlockedIndefinitelyOnMVar</a>,
°5u<a>BlockedIndefinitelyOnSTM</a>, and <a>ThreadKilled</a>, and passes
°5uall other exceptions to the uncaught exception handler.
forkIO :: IO () -> IO ThreadId

-- | Put a value into an <a>MVar</a>. If the <a>MVar</a> is currently full,
°5u<a>putMVar</a> will wait until it becomes empty.
°5u
°5uThere are two further important properties of <a>putMVar</a>:
°5u
°5u<ul>
°5u<li><a>putMVar</a> is single-wakeup. That is, if there are multiple
°5uthreads blocked in <a>putMVar</a>, and the <a>MVar</a> becomes empty,
°5uonly one thread will be woken up. The runtime guarantees that the
°5uwoken thread completes its <a>putMVar</a> operation.</li>
°5u<li>When multiple threads are blocked on an <a>MVar</a>, they are
°5uwoken up in FIFO order. This is useful for providing fairness
°5uproperties of abstractions built using <a>MVar</a>s.</li>
°5u</ul>
putMVar :: () => MVar a -> a -> IO ()

-- | Atomically read the contents of an <a>MVar</a>. If the <a>MVar</a> is
°5ucurrently empty, <a>readMVar</a> will wait until its full.
°5u<a>readMVar</a> is guaranteed to receive the next <a>putMVar</a>.
°5u
°5u<a>readMVar</a> is multiple-wakeup, so when multiple readers are
°5ublocked on an <a>MVar</a>, all of them are woken up at the same time.
°5u
°5u<i>Compatibility note:</i> Prior to base 4.7, <a>readMVar</a> was a
°5ucombination of <a>takeMVar</a> and <a>putMVar</a>. This mean that in
°5uthe presence of other threads attempting to <a>putMVar</a>,
°5u<a>readMVar</a> could block. Furthermore, <a>readMVar</a> would not
°5ureceive the next <a>putMVar</a> if there was already a pending thread
°5ublocked on <a>takeMVar</a>. The old behavior can be recovered by
°5uimplementing 'readMVar as follows:
°5u
°5u<pre>
°5ureadMVar :: MVar a -&gt; IO a
°5ureadMVar m =
°5u  mask_ $ do
°5u    a &lt;- takeMVar m
°5u    putMVar m a
°5u    return a
°5u</pre>
readMVar :: () => MVar a -> IO a

-- | Return the contents of the <a>MVar</a>. If the <a>MVar</a> is
°5ucurrently empty, <a>takeMVar</a> will wait until it is full. After a
°5u<a>takeMVar</a>, the <a>MVar</a> is left empty.
°5u
°5uThere are two further important properties of <a>takeMVar</a>:
°5u
°5u<ul>
°5u<li><a>takeMVar</a> is single-wakeup. That is, if there are multiple
°5uthreads blocked in <a>takeMVar</a>, and the <a>MVar</a> becomes full,
°5uonly one thread will be woken up. The runtime guarantees that the
°5uwoken thread completes its <a>takeMVar</a> operation.</li>
°5u<li>When multiple threads are blocked on an <a>MVar</a>, they are
°5uwoken up in FIFO order. This is useful for providing fairness
°5uproperties of abstractions built using <a>MVar</a>s.</li>
°5u</ul>
takeMVar :: () => MVar a -> IO a

-- | Create an <a>MVar</a> which is initially empty.
newEmptyMVar :: () => IO MVar a

-- | A variant of <a>bracket</a> where the return value from the first
°5ucomputation is not required.
bracket_ :: () => IO a -> IO b -> IO c -> IO c

-- | A specialised variant of <a>bracket</a> with just a computation to run
°5uafterward.
finally :: () => IO a -> IO b -> IO a

-- | When you want to acquire a resource, do some work with it, and then
°5urelease the resource, it is a good idea to use <a>bracket</a>, because
°5u<a>bracket</a> will install the necessary exception handler to release
°5uthe resource in the event that an exception is raised during the
°5ucomputation. If an exception is raised, then <a>bracket</a> will
°5ure-raise the exception (after performing the release).
°5u
°5uA common example is opening a file:
°5u
°5u<pre>
°5ubracket
°5u  (openFile "filename" ReadMode)
°5u  (hClose)
°5u  (\fileHandle -&gt; do { ... })
°5u</pre>
°5u
°5uThe arguments to <a>bracket</a> are in this order so that we can
°5upartially apply it, e.g.:
°5u
°5u<pre>
°5uwithFile name mode = bracket (openFile name mode) hClose
°5u</pre>
bracket :: () => IO a -> a -> IO b -> a -> IO c -> IO c

-- | Like <a>finally</a>, but only performs the final action if there was
°5uan exception raised by the computation.
onException :: () => IO a -> IO b -> IO a

-- | Similar to <a>catch</a>, but returns an <a>Either</a> result which is
°5u<tt>(<a>Right</a> a)</tt> if no exception of type <tt>e</tt> was
°5uraised, or <tt>(<a>Left</a> ex)</tt> if an exception of type
°5u<tt>e</tt> was raised and its value is <tt>ex</tt>. If any other type
°5uof exception is raised than it will be propogated up to the next
°5uenclosing exception handler.
°5u
°5u<pre>
°5utry a = catch (Right `liftM` a) (return . Left)
°5u</pre>
try :: Exception e => IO a -> IO Either e a

-- | Executes an IO computation with asynchronous exceptions <i>masked</i>.
°5uThat is, any thread which attempts to raise an exception in the
°5ucurrent thread with <a>throwTo</a> will be blocked until asynchronous
°5uexceptions are unmasked again.
°5u
°5uThe argument passed to <a>mask</a> is a function that takes as its
°5uargument another function, which can be used to restore the prevailing
°5umasking state within the context of the masked computation. For
°5uexample, a common way to use <a>mask</a> is to protect the acquisition
°5uof a resource:
°5u
°5u<pre>
°5umask $ \restore -&gt; do
°5u    x &lt;- acquire
°5u    restore (do_something_with x) `onException` release
°5u    release
°5u</pre>
°5u
°5uThis code guarantees that <tt>acquire</tt> is paired with
°5u<tt>release</tt>, by masking asynchronous exceptions for the critical
°5uparts. (Rather than write this code yourself, it would be better to
°5uuse <a>bracket</a> which abstracts the general pattern).
°5u
°5uNote that the <tt>restore</tt> action passed to the argument to
°5u<a>mask</a> does not necessarily unmask asynchronous exceptions, it
°5ujust restores the masking state to that of the enclosing context. Thus
°5uif asynchronous exceptions are already masked, <a>mask</a> cannot be
°5uused to unmask exceptions again. This is so that if you call a library
°5ufunction with exceptions masked, you can be sure that the library call
°5uwill not be able to unmask exceptions again. If you are writing
°5ulibrary code and need to use asynchronous exceptions, the only way is
°5uto create a new thread; see <a>forkIOWithUnmask</a>.
°5u
°5uAsynchronous exceptions may still be received while in the masked
°5ustate if the masked thread <i>blocks</i> in certain ways; see
°5u<a>Control.Exception#interruptible</a>.
°5u
°5uThreads created by <a>forkIO</a> inherit the <a>MaskingState</a> from
°5uthe parent; that is, to start a thread in the
°5u<a>MaskedInterruptible</a> state, use <tt>mask_ $ forkIO ...</tt>.
°5uThis is particularly useful if you need to establish an exception
°5uhandler in the forked thread before any asynchronous exceptions are
°5ureceived. To create a a new thread in an unmasked state use
°5u<a>forkIOWithUnmask</a>.
mask :: () => forall a. () => IO a -> IO a -> IO b -> IO b

-- | A variant of <a>throw</a> that can only be used within the <a>IO</a>
°5umonad.
°5u
°5uAlthough <a>throwIO</a> has a type that is an instance of the type of
°5u<a>throw</a>, the two functions are subtly different:
°5u
°5u<pre>
°5uthrow e   `seq` x  ===&gt; throw e
°5uthrowIO e `seq` x  ===&gt; x
°5u</pre>
°5u
°5uThe first example will cause the exception <tt>e</tt> to be raised,
°5uwhereas the second one won't. In fact, <a>throwIO</a> will only cause
°5uan exception to be raised when it is used within the <a>IO</a> monad.
°5uThe <a>throwIO</a> variant should be used in preference to
°5u<a>throw</a> to raise an exception within the <a>IO</a> monad because
°5uit guarantees ordering with respect to other <a>IO</a> operations,
°5uwhereas <a>throw</a> does not.
throwIO :: Exception e => e -> IO a

-- | This is the simplest of the exception-catching functions. It takes a
°5usingle argument, runs it, and if an exception is raised the "handler"
°5uis executed, with the value of the exception passed as an argument.
°5uOtherwise, the result is returned as normal. For example:
°5u
°5u<pre>
°5ucatch (readFile f)
°5u      (\e -&gt; do let err = show (e :: IOException)
°5u                hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
°5u                return "")
°5u</pre>
°5u
°5uNote that we have to give a type signature to <tt>e</tt>, or the
°5uprogram will not typecheck as the type is ambiguous. While it is
°5upossible to catch exceptions of any type, see the section "Catching
°5uall exceptions" (in <a>Control.Exception</a>) for an explanation of
°5uthe problems with doing so.
°5u
°5uFor catching exceptions in pure (non-<a>IO</a>) expressions, see the
°5ufunction <a>evaluate</a>.
°5u
°5uNote that due to Haskell's unspecified evaluation order, an expression
°5umay throw one of several possible exceptions: consider the expression
°5u<tt>(error "urk") + (1 `div` 0)</tt>. Does the expression throw
°5u<tt>ErrorCall "urk"</tt>, or <tt>DivideByZero</tt>?
°5u
°5uThe answer is "it might throw either"; the choice is
°5unon-deterministic. If you are catching any type of exception then you
°5umight catch either. If you are calling <tt>catch</tt> with type <tt>IO
°5uInt -&gt; (ArithException -&gt; IO Int) -&gt; IO Int</tt> then the
°5uhandler may get run with <tt>DivideByZero</tt> as an argument, or an
°5u<tt>ErrorCall "urk"</tt> exception may be propogated further up. If
°5uyou call it again, you might get a the opposite behaviour. This is ok,
°5ubecause <a>catch</a> is an <a>IO</a> computation.
catch :: Exception e => IO a -> e -> IO a -> IO a

-- | The <tt>SomeException</tt> type is the root of the exception type
°5uhierarchy. When an exception of type <tt>e</tt> is thrown, behind the
°5uscenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException

-- | The reverse of <a>when</a>.
unless :: Applicative f => Bool -> f () -> f ()

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: Applicative m => Int -> m a -> m ()

-- | Right-to-left Kleisli composition of monads.
°5u<tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped.
°5u
°5uNote how this operator resembles function composition
°5u<tt>(<a>.</a>)</tt>:
°5u
°5u<pre>
°5u(.)   ::            (b -&gt;   c) -&gt; (a -&gt;   b) -&gt; a -&gt;   c
°5u(&lt;=&lt;) :: Monad m =&gt; (b -&gt; m c) -&gt; (a -&gt; m b) -&gt; a -&gt; m c
°5u</pre>
(<=<) :: Monad m => b -> m c -> a -> m b -> a -> m c
infixr 1 <=<

-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => a -> m b -> b -> m c -> a -> m c
infixr 1 >=>

-- | Conditional execution of <a>Applicative</a> expressions. For example,
°5u
°5u<pre>
°5uwhen debug (putStrLn "Debugging")
°5u</pre>
°5u
°5uwill output the string <tt>Debugging</tt> if the Boolean value
°5u<tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()

-- | Bitwise "and"
(.&.) :: Bits a => a -> a -> a
infixl 7 .&.

-- | Bitwise "or"
(.|.) :: Bits a => a -> a -> a
infixl 5 .|.

-- | Reverse all the bits in the argument
complement :: Bits a => a -> a

-- | Convert a letter to the corresponding upper-case letter, if any. Any
°5uother character is returned unchanged.
toUpper :: Char -> Char

-- | Convert a letter to the corresponding lower-case letter, if any. Any
°5uother character is returned unchanged.
toLower :: Char -> Char

-- | Selects alphabetic Unicode characters (lower-case, upper-case and
°5utitle-case letters, plus letters of caseless scripts and modifiers
°5uletters). This function is equivalent to <a>isLetter</a>.
isAlpha :: Char -> Bool

-- | Selects the first 128 characters of the Unicode character set,
°5ucorresponding to the ASCII character set.
isAscii :: Char -> Bool

-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
°5uversion that doesn't ignore the results see <a>for</a>.
°5u
°5u<pre>
°5u&gt;&gt;&gt; for_ [1..4] print
°5u1
°5u2
°5u3
°5u4
°5u</pre>
for_ :: (Foldable t, Applicative f) => t a -> a -> f b -> f ()

-- | Map each element of a structure to an action, evaluate these actions
°5ufrom left to right, and ignore the results. For a version that doesn't
°5uignore the results see <a>traverse</a>.
traverse_ :: (Foldable t, Applicative f) => a -> f b -> t a -> f ()
on :: () => b -> b -> c -> a -> b -> a -> a -> c
infixl 0 `on`

-- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and
°5ureturns a list of all the <a>Just</a> values.
°5u
°5u<h4><b>Examples</b></h4>
°5u
°5uBasic usage:
°5u
°5u<pre>
°5u&gt;&gt;&gt; catMaybes [Just 1, Nothing, Just 3]
°5u[1,3]
°5u</pre>
°5u
°5uWhen constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
°5ube used to return all of the "success" results (if the list is the
°5uresult of a <a>map</a>, then <a>mapMaybe</a> would be more
°5uappropriate):
°5u
°5u<pre>
°5u&gt;&gt;&gt; import Text.Read ( readMaybe )
°5u
°5u&gt;&gt;&gt; [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
°5u[Just 1,Nothing,Just 3]
°5u
°5u&gt;&gt;&gt; catMaybes $ [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
°5u[1,3]
°5u</pre>
catMaybes :: () => [Maybe a] -> [a]

-- | The <a>maybeToList</a> function returns an empty list when given
°5u<a>Nothing</a> or a singleton list when not given <a>Nothing</a>.
°5u
°5u<h4><b>Examples</b></h4>
°5u
°5uBasic usage:
°5u
°5u<pre>
°5u&gt;&gt;&gt; maybeToList (Just 7)
°5u[7]
°5u</pre>
°5u
°5u<pre>
°5u&gt;&gt;&gt; maybeToList Nothing
°5u[]
°5u</pre>
°5u
°5uOne can use <a>maybeToList</a> to avoid pattern matching when combined
°5uwith a function that (safely) works on lists:
°5u
°5u<pre>
°5u&gt;&gt;&gt; import Text.Read ( readMaybe )
°5u
°5u&gt;&gt;&gt; sum $ maybeToList (readMaybe "3")
°5u3
°5u
°5u&gt;&gt;&gt; sum $ maybeToList (readMaybe "")
°5u0
°5u</pre>
maybeToList :: () => Maybe a -> [a]

-- | The <a>fromMaybe</a> function takes a default value and and
°5u<a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
°5uthe default values; otherwise, it returns the value contained in the
°5u<a>Maybe</a>.
°5u
°5u<h4><b>Examples</b></h4>
°5u
°5uBasic usage:
°5u
°5u<pre>
°5u&gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
°5u"Hello, World!"
°5u</pre>
°5u
°5u<pre>
°5u&gt;&gt;&gt; fromMaybe "" Nothing
°5u""
°5u</pre>
°5u
°5uRead an integer from a string using <tt>readMaybe</tt>. If we fail to
°5uparse an integer, we want to return <tt>0</tt> by default:
°5u
°5u<pre>
°5u&gt;&gt;&gt; import Text.Read ( readMaybe )
°5u
°5u&gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
°5u5
°5u
°5u&gt;&gt;&gt; fromMaybe 0 (readMaybe "")
°5u0
°5u</pre>
fromMaybe :: () => a -> Maybe a -> a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | Fold a list using the monoid.
°5u
°5uFor most types, the default definition for <a>mconcat</a> will be
°5uused, but the function is included in the class definition so that an
°5uoptimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a

-- | Write a new value into an <a>IORef</a>
writeIORef :: () => IORef a -> a -> IO ()

-- | Read the value of an <a>IORef</a>
readIORef :: () => IORef a -> IO a

-- | Build a new <a>IORef</a>
newIORef :: () => a -> IO IORef a

-- | A mutable variable in the <a>IO</a> monad
data IORef a

-- | <a>for</a> is <a>traverse</a> with its arguments flipped. For a
°5uversion that ignores the results see <a>for_</a>.
for :: (Traversable t, Applicative f) => t a -> a -> f b -> f t b

-- | A value of type <tt><a>Ptr</a> a</tt> represents a pointer to an
°5uobject, or an array of objects, which may be marshalled to or from
°5uHaskell values of type <tt>a</tt>.
°5u
°5uThe type <tt>a</tt> will often be an instance of class <a>Storable</a>
°5uwhich provides the marshalling operations. However this is not
°5uessential, and you can provide your own operations to access the
°5upointer. For example you might write small foreign functions to get or
°5uset the fields of a C <tt>struct</tt>.
data Ptr a

-- | Temporarily store a list of storable values in memory (like
°5u<a>with</a>, but for multiple elements).
withArray :: Storable a => [a] -> Ptr a -> IO b -> IO b

-- | Temporarily allocate space for the given number of elements (like
°5u<a>alloca</a>, but for multiple elements).
allocaArray :: Storable a => Int -> Ptr a -> IO b -> IO b

-- | Converts a <tt>withXXX</tt> combinator into one marshalling a value
°5uwrapped into a <a>Maybe</a>, using <a>nullPtr</a> to represent
°5u<a>Nothing</a>.
maybeWith :: () => a -> Ptr b -> IO c -> IO c -> Maybe a -> Ptr b -> IO c -> IO c

-- | <tt><a>with</a> val f</tt> executes the computation <tt>f</tt>,
°5upassing as argument a pointer to a temporarily allocated block of
°5umemory into which <tt>val</tt> has been marshalled (the combination of
°5u<a>alloca</a> and <a>poke</a>).
°5u
°5uThe memory is freed when <tt>f</tt> terminates (either normally or via
°5uan exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
°5uused after this.
with :: Storable a => a -> Ptr a -> IO b -> IO b
allocaBytesAligned :: () => Int -> Int -> Ptr a -> IO b -> IO b

-- | <tt><a>allocaBytes</a> n f</tt> executes the computation <tt>f</tt>,
°5upassing as argument a pointer to a temporarily allocated block of
°5umemory of <tt>n</tt> bytes. The block of memory is sufficiently
°5ualigned for any of the basic foreign types that fits into a memory
°5ublock of the allocated size.
°5u
°5uThe memory is freed when <tt>f</tt> terminates (either normally or via
°5uan exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
°5uused after this.
allocaBytes :: () => Int -> Ptr a -> IO b -> IO b

-- | <tt><a>alloca</a> f</tt> executes the computation <tt>f</tt>, passing
°5uas argument a pointer to a temporarily allocated block of memory
°5usufficient to hold values of type <tt>a</tt>.
°5u
°5uThe memory is freed when <tt>f</tt> terminates (either normally or via
°5uan exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
°5uused after this.
alloca :: Storable a => Ptr a -> IO b -> IO b

-- | The member functions of this class facilitate writing values of
°5uprimitive types to raw memory (which may have been allocated with the
°5uabove mentioned routines) and reading values from blocks of raw
°5umemory. The class, furthermore, includes support for computing the
°5ustorage requirements and alignment restrictions of storable types.
°5u
°5uMemory addresses are represented as values of type <tt><a>Ptr</a>
°5ua</tt>, for some <tt>a</tt> which is an instance of class
°5u<a>Storable</a>. The type argument to <a>Ptr</a> helps provide some
°5uvaluable type safety in FFI code (you can't mix pointers of different
°5utypes without an explicit cast), while helping the Haskell type system
°5ufigure out which marshalling method is needed for a given pointer.
°5u
°5uAll marshalling between Haskell and a foreign language ultimately
°5uboils down to translating Haskell data structures into the binary
°5urepresentation of a corresponding data structure of the foreign
°5ulanguage and vice versa. To code this marshalling in Haskell, it is
°5unecessary to manipulate primitive data types stored in unstructured
°5umemory blocks. The class <a>Storable</a> facilitates this manipulation
°5uon all types for which it is instantiated, which are the standard
°5ubasic types of Haskell, the fixed size <tt>Int</tt> types
°5u(<a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>), the fixed
°5usize <tt>Word</tt> types (<a>Word8</a>, <a>Word16</a>, <a>Word32</a>,
°5u<a>Word64</a>), <a>StablePtr</a>, all types from
°5u<a>Foreign.C.Types</a>, as well as <a>Ptr</a>.
class Storable a

-- | Computes the storage requirements (in bytes) of the argument. The
°5uvalue of the argument is not used.
sizeOf :: Storable a => a -> Int

-- | Computes the alignment constraint of the argument. An alignment
°5uconstraint <tt>x</tt> is fulfilled by any address divisible by
°5u<tt>x</tt>. The value of the argument is not used.
alignment :: Storable a => a -> Int

-- | Read a value from a memory area regarded as an array of values of the
°5usame kind. The first argument specifies the start address of the array
°5uand the second the index into the array (the first element of the
°5uarray has index <tt>0</tt>). The following equality holds,
°5u
°5u<pre>
°5upeekElemOff addr idx = IOExts.fixIO $ \result -&gt;
°5u  peek (addr `plusPtr` (idx * sizeOf result))
°5u</pre>
°5u
°5uNote that this is only a specification, not necessarily the concrete
°5uimplementation of the function.
peekElemOff :: Storable a => Ptr a -> Int -> IO a

-- | Write a value to a memory area regarded as an array of values of the
°5usame kind. The following equality holds:
°5u
°5u<pre>
°5upokeElemOff addr idx x = 
°5u  poke (addr `plusPtr` (idx * sizeOf x)) x
°5u</pre>
pokeElemOff :: Storable a => Ptr a -> Int -> a -> IO ()

-- | Read a value from a memory location given by a base address and
°5uoffset. The following equality holds:
°5u
°5u<pre>
°5upeekByteOff addr off = peek (addr `plusPtr` off)
°5u</pre>
peekByteOff :: Storable a => Ptr b -> Int -> IO a

-- | Write a value to a memory location given by a base address and offset.
°5uThe following equality holds:
°5u
°5u<pre>
°5upokeByteOff addr off x = poke (addr `plusPtr` off) x
°5u</pre>
pokeByteOff :: Storable a => Ptr b -> Int -> a -> IO ()

-- | Read a value from the given memory location.
°5u
°5uNote that the peek and poke functions might require properly aligned
°5uaddresses to function correctly. This is architecture dependent; thus,
°5uportable code should ensure that when peeking or poking values of some
°5utype <tt>a</tt>, the alignment constraint for <tt>a</tt>, as given by
°5uthe function <a>alignment</a> is fulfilled.
peek :: Storable a => Ptr a -> IO a

-- | Write the given value to the given memory location. Alignment
°5urestrictions might apply; see <a>peek</a>.
poke :: Storable a => Ptr a -> a -> IO ()

-- | Advances the given address by the given offset in bytes.
plusPtr :: () => Ptr a -> Int -> Ptr b

-- | The constant <a>nullPtr</a> contains a distinguished value of
°5u<a>Ptr</a> that is not associated with a valid memory location.
nullPtr :: () => Ptr a

-- | as <a>throwErrnoIfMinus1_</a>, but exceptions include the given path
°5uwhen appropriate.
throwErrnoPathIfMinus1_ :: (Eq a, Num a) => String -> FilePath -> IO a -> IO ()

-- | Throw an <a>IOError</a> corresponding to the current value of
°5u<a>getErrno</a> if the <a>IO</a> action returns <a>nullPtr</a>.
throwErrnoIfNull :: () => String -> IO Ptr a -> IO Ptr a

-- | as <a>throwErrnoIfMinus1</a>, but discards the result.
throwErrnoIfMinus1Retry_ :: (Eq a, Num a) => String -> IO a -> IO ()

-- | as <a>throwErrnoIfMinus1</a>, but discards the result.
throwErrnoIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO ()

-- | Marshal a Haskell string into a NUL terminated C wide string using
°5utemporary storage.
°5u
°5u<ul>
°5u<li>the Haskell string may <i>not</i> contain any NUL characters</li>
°5u<li>the memory is freed when the subcomputation terminates (either
°5unormally or via an exception), so the pointer to the temporary storage
°5umust <i>not</i> be used after this.</li>
°5u</ul>
withCWString :: () => String -> CWString -> IO a -> IO a

-- | Marshal a C wide string with explicit length into a Haskell string.
peekCWStringLen :: CWStringLen -> IO String

-- | Marshal a Haskell string into a NUL terminated C string using
°5utemporary storage.
°5u
°5u<ul>
°5u<li>the Haskell string may <i>not</i> contain any NUL characters</li>
°5u<li>the memory is freed when the subcomputation terminates (either
°5unormally or via an exception), so the pointer to the temporary storage
°5umust <i>not</i> be used after this.</li>
°5u</ul>
withCString :: () => String -> CString -> IO a -> IO a

-- | Marshal a NUL terminated C string into a Haskell string.
peekCString :: CString -> IO String

-- | A C string is a reference to an array of C characters terminated by
°5uNUL.
type CString = Ptr CChar

-- | A C wide string is a reference to an array of C wide characters
°5uterminated by NUL.
type CWString = Ptr CWchar

-- | Haskell type representing the C <tt>unsigned char</tt> type.
newtype CUChar
CUChar :: Word8 -> CUChar

-- | Haskell type representing the C <tt>unsigned short</tt> type.
newtype CUShort
CUShort :: Word16 -> CUShort

-- | Haskell type representing the C <tt>int</tt> type.
newtype CInt
CInt :: Int32 -> CInt

-- | Haskell type representing the C <tt>long</tt> type.
newtype CLong
CLong :: Int64 -> CLong

-- | Haskell type representing the C <tt>unsigned long</tt> type.
newtype CULong
CULong :: Word64 -> CULong

-- | Haskell type representing the C <tt>wchar_t</tt> type.
newtype CWchar
CWchar :: Int32 -> CWchar

-- | Haskell type representing the C <tt>time_t</tt> type.
newtype CTime
CTime :: Int64 -> CTime

-- | The Unicode encoding of the current locale, but allowing arbitrary
°5uundecodable bytes to be round-tripped through it.
°5u
°5uThis <a>TextEncoding</a> is used to decode and encode command line
°5uarguments and environment variables on non-Windows platforms.
°5u
°5uOn Windows, this encoding *should not* be used if possible because the
°5uuse of code pages is deprecated: Strings should be retrieved via the
°5u"wide" W-family of UTF-16 APIs instead
getFileSystemEncoding :: IO TextEncoding

-- | An abstract type that contains a value for each variant of
°5u<a>IOError</a>.
data IOErrorType
OtherError :: IOErrorType
InappropriateType :: IOErrorType
UnsupportedOperation :: IOErrorType

-- | Computation <a>getEnv</a> <tt>var</tt> returns the value of the
°5uenvironment variable <tt>var</tt>. For the inverse, POSIX users can
°5uuse <a>putEnv</a>.
°5u
°5uThis computation may fail with:
°5u
°5u<ul>
°5u<li><a>isDoesNotExistError</a> if the environment variable does not
°5uexist.</li>
°5u</ul>
getEnv :: String -> IO String

-- | Computation <a>getArgs</a> returns a list of the program's command
°5uline arguments (not including the program name).
getArgs :: IO [String]

-- | The computation <a>exitFailure</a> is equivalent to <a>exitWith</a>
°5u<tt>(</tt><a>ExitFailure</a> <i>exitfail</i><tt>)</tt>, where
°5u<i>exitfail</i> is implementation-dependent.
exitFailure :: () => IO a

-- | Like <a>openTempFile</a>, but opens the file in binary mode. See
°5u<a>openBinaryFile</a> for more comments.
openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)

-- | <tt><a>withBinaryFile</a> name mode act</tt> opens a file using
°5u<a>openBinaryFile</a> and passes the resulting handle to the
°5ucomputation <tt>act</tt>. The handle will be closed on exit from
°5u<a>withBinaryFile</a>, whether by normal termination or by raising an
°5uexception.
withBinaryFile :: () => FilePath -> IOMode -> Handle -> IO r -> IO r

-- | Computation <a>hClose</a> <tt>hdl</tt> makes handle <tt>hdl</tt>
°5uclosed. Before the computation finishes, if <tt>hdl</tt> is writable
°5uits buffer is flushed as for <a>hFlush</a>. Performing <a>hClose</a>
°5uon a handle that has already been closed has no effect; doing so is
°5unot an error. All other operations on a closed handle will fail. If
°5u<a>hClose</a> fails for any reason, any further operations (apart from
°5u<a>hClose</a>) on the handle will still fail as if <tt>hdl</tt> had
°5ubeen successfully closed.
hClose :: Handle -> IO ()

-- | A handle managing output to the Haskell program's standard error
°5uchannel.
stderr :: Handle

-- | <a>hGetBuf</a> <tt>hdl buf count</tt> reads data from the handle
°5u<tt>hdl</tt> into the buffer <tt>buf</tt> until either EOF is reached
°5uor <tt>count</tt> 8-bit bytes have been read. It returns the number of
°5ubytes actually read. This may be zero if EOF was reached before any
°5udata was read (or if <tt>count</tt> is zero).
°5u
°5u<a>hGetBuf</a> never raises an EOF exception, instead it returns a
°5uvalue smaller than <tt>count</tt>.
°5u
°5uIf the handle is a pipe or socket, and the writing end is closed,
°5u<a>hGetBuf</a> will behave as if EOF was reached.
°5u
°5u<a>hGetBuf</a> ignores the prevailing <tt>TextEncoding</tt> and
°5u<a>NewlineMode</a> on the <a>Handle</a>, and reads bytes directly.
hGetBuf :: () => Handle -> Ptr a -> Int -> IO Int

-- | <a>hPutBuf</a> <tt>hdl buf count</tt> writes <tt>count</tt> 8-bit
°5ubytes from the buffer <tt>buf</tt> to the handle <tt>hdl</tt>. It
°5ureturns ().
°5u
°5u<a>hPutBuf</a> ignores any text encoding that applies to the
°5u<a>Handle</a>, writing the bytes directly to the underlying file or
°5udevice.
°5u
°5u<a>hPutBuf</a> ignores the prevailing <tt>TextEncoding</tt> and
°5u<a>NewlineMode</a> on the <a>Handle</a>, and writes bytes directly.
°5u
°5uThis operation may fail with:
°5u
°5u<ul>
°5u<li><a>ResourceVanished</a> if the handle is a pipe or socket, and the
°5ureading end is closed. (If this is a POSIX system, and the program has
°5unot asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead,
°5uwhose default action is to terminate the program).</li>
°5u</ul>
hPutBuf :: () => Handle -> Ptr a -> Int -> IO ()

-- | The same as <a>hPutStr</a>, but adds a newline character.
hPutStrLn :: Handle -> String -> IO ()

-- | Computation <a>hPutStr</a> <tt>hdl s</tt> writes the string <tt>s</tt>
°5uto the file or channel managed by <tt>hdl</tt>.
°5u
°5uThis operation may fail with:
°5u
°5u<ul>
°5u<li><a>isFullError</a> if the device is full; or</li>
°5u<li><a>isPermissionError</a> if another system resource limit would be
°5uexceeded.</li>
°5u</ul>
hPutStr :: Handle -> String -> IO ()

-- | The action <a>hFlush</a> <tt>hdl</tt> causes any items buffered for
°5uoutput in handle <tt>hdl</tt> to be sent immediately to the operating
°5usystem.
°5u
°5uThis operation may fail with:
°5u
°5u<ul>
°5u<li><tt>isFullError</tt> if the device is full;</li>
°5u<li><tt>isPermissionError</tt> if a system resource limit would be
°5uexceeded. It is unspecified whether the characters in the buffer are
°5udiscarded or retained under these circumstances.</li>
°5u</ul>
hFlush :: Handle -> IO ()

-- | A handle managing output to the Haskell program's standard output
°5uchannel.
stdout :: Handle

-- | Haskell defines operations to read and write characters from and to
°5ufiles, represented by values of type <tt>Handle</tt>. Each value of
°5uthis type is a <i>handle</i>: a record used by the Haskell run-time
°5usystem to <i>manage</i> I/O with file system objects. A handle has at
°5uleast the following properties:
°5u
°5u<ul>
°5u<li>whether it manages input or output or both;</li>
°5u<li>whether it is <i>open</i>, <i>closed</i> or
°5u<i>semi-closed</i>;</li>
°5u<li>whether the object is seekable;</li>
°5u<li>whether buffering is disabled, or enabled on a line or block
°5ubasis;</li>
°5u<li>a buffer (whose length may be zero).</li>
°5u</ul>
°5u
°5uMost handles will also have a current I/O position indicating where
°5uthe next input or output operation will occur. A handle is
°5u<i>readable</i> if it manages only input or both input and output;
°5ulikewise, it is <i>writable</i> if it manages only output or both
°5uinput and output. A handle is <i>open</i> when first allocated. Once
°5uit is closed it can no longer be used for either input or output,
°5uthough an implementation cannot re-use its storage while references
°5uremain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
°5uThe string produced by showing a handle is system dependent; it should
°5uinclude enough information to identify the handle for debugging. A
°5uhandle is equal according to <a>==</a> only to itself; no attempt is
°5umade to compare the internal state of different handles for equality.
data Handle

-- | See <a>openFile</a>
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode

-- | The <a>catchIOError</a> function establishes a handler that receives
°5uany <a>IOError</a> raised in the action protected by
°5u<a>catchIOError</a>. An <a>IOError</a> is caught by the most recent
°5uhandler established by one of the exception handling functions. These
°5uhandlers are not selective: all <a>IOError</a>s are caught. Exception
°5upropagation must be explicitly provided in a handler by re-raising any
°5uunwanted exceptions. For example, in
°5u
°5u<pre>
°5uf = catchIOError g (\e -&gt; if IO.isEOFError e then return [] else ioError e)
°5u</pre>
°5u
°5uthe function <tt>f</tt> returns <tt>[]</tt> when an end-of-file
°5uexception (cf. <a>isEOFError</a>) occurs in <tt>g</tt>; otherwise, the
°5uexception is propagated to the next outer handler.
°5u
°5uWhen an exception propagates outside the main program, the Haskell
°5usystem prints the associated <a>IOError</a> value and exits the
°5uprogram.
°5u
°5uNon-I/O exceptions are not caught by this variant; to catch all
°5uexceptions, use <a>catch</a> from <a>Control.Exception</a>.
catchIOError :: () => IO a -> IOError -> IO a -> IO a

-- | Catch any <a>IOError</a> that occurs in the computation and throw a
°5umodified version.
modifyIOError :: () => IOError -> IOError -> IO a -> IO a
ioeSetFileName :: IOError -> FilePath -> IOError
ioeSetLocation :: IOError -> String -> IOError
ioeSetErrorString :: IOError -> String -> IOError
ioeGetLocation :: IOError -> String
ioeGetErrorString :: IOError -> String
ioeGetErrorType :: IOError -> IOErrorType

-- | I/O error where the operation failed because the user does not have
°5usufficient operating system privilege to perform that operation.
permissionErrorType :: IOErrorType

-- | I/O error where the operation is not possible.
illegalOperationErrorType :: IOErrorType

-- | An error indicating that an <a>IO</a> operation failed because the
°5uuser does not have sufficient operating system privilege to perform
°5uthat operation.
isPermissionError :: IOError -> Bool

-- | An error indicating that an <a>IO</a> operation failed because the
°5uoperation was not possible. Any computation which returns an <a>IO</a>
°5uresult may fail with <a>isIllegalOperation</a>. In some cases, an
°5uimplementation will not be able to distinguish between the possible
°5uerror causes. In this case it should fail with
°5u<a>isIllegalOperation</a>.
isIllegalOperation :: IOError -> Bool

-- | An error indicating that an <a>IO</a> operation failed because one of
°5uits arguments does not exist.
isDoesNotExistError :: IOError -> Bool

-- | An error indicating that an <a>IO</a> operation failed because one of
°5uits arguments already exists.
isAlreadyExistsError :: IOError -> Bool

-- | Construct an <a>IOError</a> of the given type where the second
°5uargument describes the error location and the third and fourth
°5uargument contain the file handle and file path of the file involved in
°5uthe error if applicable.
mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError

-- | The construct <a>tryIOError</a> <tt>comp</tt> exposes IO errors which
°5uoccur within a computation, and which are not fully handled.
°5u
°5uNon-I/O exceptions are not caught by this variant; to catch all
°5uexceptions, use <a>try</a> from <a>Control.Exception</a>.
tryIOError :: () => IO a -> IO Either IOError a

-- | Construct an <a>IOError</a> value with a string describing the error.
°5uThe <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a>
°5uclass raises a <a>userError</a>, thus:
°5u
°5u<pre>
°5uinstance Monad IO where
°5u  ...
°5u  fail s = ioError (userError s)
°5u</pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
°5uoperation may raise an <a>IOError</a> instead of returning a result.
°5uFor a more general type of exception, including also those that arise
°5uin pure code, see <a>Exception</a>.
°5u
°5uIn Haskell 2010, this is an opaque type.
type IOError = IOException
withFilePath :: () => FilePath -> CString -> IO a -> IO a
type EpochTime = CTime

-- | Wrap an <a>IO</a> computation to time out and return <tt>Nothing</tt>
°5uin case no result is available within <tt>n</tt> microseconds
°5u(<tt>1/10^6</tt> seconds). In case a result is available before the
°5utimeout expires, <tt>Just a</tt> is returned. A negative timeout
°5uinterval means "wait indefinitely". When specifying long timeouts, be
°5ucareful not to exceed <tt>maxBound :: Int</tt>.
°5u
°5u<pre>
°5u&gt;&gt;&gt; timeout 1000000 (threadDelay 1000 *&gt; pure "finished on time")
°5uJust "finished on time"
°5u</pre>
°5u
°5u<pre>
°5u&gt;&gt;&gt; timeout 10000 (threadDelay 100000 *&gt; pure "finished on time")
°5uNothing
°5u</pre>
°5u
°5uThe design of this combinator was guided by the objective that
°5u<tt>timeout n f</tt> should behave exactly the same as <tt>f</tt> as
°5ulong as <tt>f</tt> doesn't time out. This means that <tt>f</tt> has
°5uthe same <a>myThreadId</a> it would have without the timeout wrapper.
°5uAny exceptions <tt>f</tt> might throw cancel the timeout and propagate
°5ufurther up. It also possible for <tt>f</tt> to receive exceptions
°5uthrown to it by another thread.
°5u
°5uA tricky implementation detail is the question of how to abort an
°5u<tt>IO</tt> computation. This combinator relies on asynchronous
°5uexceptions internally. The technique works very well for computations
°5uexecuting inside of the Haskell runtime system, but it doesn't work at
°5uall for non-Haskell code. Foreign function calls, for example, cannot
°5ube timed out with this combinator simply because an arbitrary C
°5ufunction cannot receive asynchronous exceptions. When <tt>timeout</tt>
°5uis used to wrap an FFI call that blocks, no timeout event can be
°5udelivered until the FFI call returns, which pretty much negates the
°5upurpose of the combinator. In practice, however, this limitation is
°5uless severe than it may sound. Standard I/O functions like
°5u<a>hGetBuf</a>, <a>hPutBuf</a>, Network.Socket.accept, or
°5u<a>hWaitForInput</a> appear to be blocking, but they really don't
°5ubecause the runtime system uses scheduling mechanisms like
°5u<tt>select(2)</tt> to perform asynchronous I/O, so it is possible to
°5uinterrupt standard socket I/O or file I/O using this combinator.
timeout :: () => Int -> IO a -> IO Maybe a


-- | Internal modules are always subject to change from version to version.
°5uThe contents of this module are also platform-dependent, hence what is
°5ushown in the Hackage documentation may differ from what is actually
°5uavailable on your system.
module System.Directory.Internal

-- | Similar to <a>try</a> but only catches a specify kind of
°5u<a>IOError</a> as specified by the predicate.
tryIOErrorType :: (IOError -> Bool) -> IO a -> IO (Either IOError a)
specializeErrorString :: String -> (IOError -> Bool) -> IO a -> IO a
ioeAddLocation :: IOError -> String -> IOError
data FileType
File :: FileType

-- | POSIX: either file or directory link; Windows: file link
SymbolicLink :: FileType
Directory :: FileType

-- | Windows only
DirectoryLink :: FileType

-- | Check whether the given <a>FileType</a> is considered a directory by
°5uthe operating system. This affects the choice of certain functions
°5ue.g. <tt>removeDirectory</tt> vs <tt>removeFile</tt>.
fileTypeIsDirectory :: FileType -> Bool
data Permissions
Permissions :: Bool -> Bool -> Bool -> Bool -> Permissions
[readable] :: Permissions -> Bool
[writable] :: Permissions -> Bool
[executable] :: Permissions -> Bool
[searchable] :: Permissions -> Bool

-- | Obtain the current working directory as an absolute path.
°5u
°5uIn a multithreaded program, the current working directory is a global
°5ustate shared among all threads of the process. Therefore, when
°5uperforming filesystem operations from multiple threads, it is highly
°5urecommended to use absolute rather than relative paths (see:
°5u<tt>makeAbsolute</tt>).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><a>isDoesNotExistError</a> or <tt>NoSuchThing</tt> There is no
°5upath referring to the working directory. <tt>[EPERM, ENOENT,
°5uESTALE...]</tt></li>
°5u<li><a>isPermissionError</a> or <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation.
°5u<tt>[EACCES]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation.</li>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5ucurrent working directory.</li>
°5u</ul>
getCurrentDirectory :: IO FilePath

-- | Convert a path into an absolute path. If the given path is relative,
°5uthe current directory is prepended. If the path is already absolute,
°5uthe path is returned unchanged. The function preserves the presence or
°5uabsence of the trailing path separator.
°5u
°5uIf the path is already absolute, the operation never fails. Otherwise,
°5uthe operation may fail with the same exceptions as
°5u<a>getCurrentDirectory</a>.
°5u
°5u(internal API)
prependCurrentDirectory :: FilePath -> IO FilePath
c_free :: Ptr a -> IO ()
c_PATH_MAX :: Maybe Int
c_realpath :: CString -> CString -> IO CString
withRealpath :: CString -> (CString -> IO a) -> IO a
type Metadata = FileStatus
getSymbolicLinkMetadata :: FilePath -> IO Metadata
getFileMetadata :: FilePath -> IO Metadata
fileTypeFromMetadata :: Metadata -> FileType
fileSizeFromMetadata :: Metadata -> Integer
accessTimeFromMetadata :: Metadata -> UTCTime
modificationTimeFromMetadata :: Metadata -> UTCTime
posix_accessTimeHiRes :: FileStatus -> POSIXTime
posix_modificationTimeHiRes :: FileStatus -> POSIXTime
type Mode = FileMode
modeFromMetadata :: Metadata -> Mode
allWriteMode :: FileMode
hasWriteMode :: Mode -> Bool
setWriteMode :: Bool -> Mode -> Mode
setFileMode :: FilePath -> Mode -> IO ()
setFilePermissions :: FilePath -> Mode -> IO ()
getAccessPermissions :: FilePath -> IO Permissions
setAccessPermissions :: FilePath -> Permissions -> IO ()
data CTimeSpec
CTimeSpec :: EpochTime -> CLong -> CTimeSpec
c_AT_FDCWD :: CInt
utimeOmit :: CTimeSpec
toCTimeSpec :: POSIXTime -> CTimeSpec
c_utimensat :: CInt -> CString -> Ptr CTimeSpec -> CInt -> IO CInt


-- | System-independent interface to directory manipulation.
module System.Directory

-- | <tt><a>createDirectory</a> dir</tt> creates a new directory
°5u<tt>dir</tt> which is initially empty, or as near to empty as the
°5uoperating system allows.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES]</tt></li>
°5u<li><a>isAlreadyExistsError</a> / <tt>AlreadyExists</tt> The operand
°5urefers to a directory that already exists. <tt> [EEXIST]</tt></li>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> The operand is not a valid directory
°5uname. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><tt>NoSuchThing</tt> There is no path to the directory.
°5u<tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources (virtual memory,
°5uprocess file descriptors, physical disk space, etc.) are available to
°5uperform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
°5u<li><a>InappropriateType</a> The path refers to an existing
°5unon-directory object. <tt>[EEXIST]</tt></li>
°5u</ul>
createDirectory :: FilePath -> IO ()

-- | <tt><a>createDirectoryIfMissing</a> parents dir</tt> creates a new
°5udirectory <tt>dir</tt> if it doesn't exist. If the first argument is
°5u<a>True</a> the function will also create all parent directories if
°5uthey are missing.
createDirectoryIfMissing :: Bool -> FilePath -> IO ()

-- | <tt><a>removeDirectory</a> dir</tt> removes an existing directory
°5u<i>dir</i>. The implementation may specify additional constraints
°5uwhich must be satisfied before a directory can be removed (e.g. the
°5udirectory has to be empty, or may not be in use by other processes).
°5uIt is not legal for an implementation to partially remove a directory
°5uunless the entire directory is removed. A conformant implementation
°5uneed not support directory removal in all situations (e.g. removal of
°5uthe root directory).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> The operand is not a valid directory
°5uname. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
°5udoes not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES, EPERM]</tt></li>
°5u<li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
°5uconstraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
°5uEEXIST]</tt></li>
°5u<li><a>UnsupportedOperation</a> The implementation does not support
°5uremoval in this situation. <tt>[EINVAL]</tt></li>
°5u<li><a>InappropriateType</a> The operand refers to an existing
°5unon-directory object. <tt>[ENOTDIR]</tt></li>
°5u</ul>
removeDirectory :: FilePath -> IO ()

-- | <tt><a>removeDirectoryRecursive</a> dir</tt> removes an existing
°5udirectory <i>dir</i> together with its contents and subdirectories.
°5uWithin this directory, symbolic links are removed without affecting
°5utheir targets.
°5u
°5uOn Windows, the operation fails if <i>dir</i> is a directory symbolic
°5ulink.
removeDirectoryRecursive :: FilePath -> IO ()

-- | Removes a file or directory at <i>path</i> together with its contents
°5uand subdirectories. Symbolic links are removed without affecting their
°5utargets. If the path does not exist, nothing happens.
°5u
°5uUnlike other removal functions, this function will also attempt to
°5udelete files marked as read-only or otherwise made unremovable due to
°5upermissions. As a result, if the removal is incomplete, the
°5upermissions or attributes on the remaining files may be altered. If
°5uthere are hard links in the directory, then permissions on all related
°5uhard links may be altered.
°5u
°5uIf an entry within the directory vanishes while
°5u<tt>removePathForcibly</tt> is running, it is silently ignored.
°5u
°5uIf an exception occurs while removing an entry,
°5u<tt>removePathForcibly</tt> will still try to remove as many entries
°5uas it can before failing with an exception. The first exception that
°5uit encountered is re-thrown.
removePathForcibly :: FilePath -> IO ()

-- | <tt><a>renameDirectory</a> old new</tt> changes the name of an
°5uexisting directory from <i>old</i> to <i>new</i>. If the <i>new</i>
°5udirectory already exists, it is atomically replaced by the <i>old</i>
°5udirectory. If the <i>new</i> directory is neither the <i>old</i>
°5udirectory nor an alias of the <i>old</i> directory, it is removed as
°5uif by <a>removeDirectory</a>. A conformant implementation need not
°5usupport renaming directories in all situations (e.g. renaming to an
°5uexisting directory, or across different physical devices), but the
°5uconstraints must be documented.
°5u
°5uOn Win32 platforms, <tt>renameDirectory</tt> fails if the <i>new</i>
°5udirectory already exists.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> Either operand is not a valid directory
°5uname. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
°5udirectory does not exist, or there is no path to the target.
°5u<tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES, EPERM]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
°5u<li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
°5uconstraints are not satisfied. <tt>[EBUSY, ENOTEMPTY,
°5uEEXIST]</tt></li>
°5u<li><a>UnsupportedOperation</a> The implementation does not support
°5urenaming in this situation. <tt>[EINVAL, EXDEV]</tt></li>
°5u<li><a>InappropriateType</a> Either path refers to an existing
°5unon-directory object. <tt>[ENOTDIR, EISDIR]</tt></li>
°5u</ul>
renameDirectory :: FilePath -> FilePath -> IO ()

-- | <tt><a>listDirectory</a> dir</tt> returns a list of <i>all</i> entries
°5uin <i>dir</i> without the special entries (<tt>.</tt> and
°5u<tt>..</tt>).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> The operand is not a valid directory
°5uname. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The directory
°5udoes not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation.
°5u<tt>[EACCES]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation. <tt>[EMFILE, ENFILE]</tt></li>
°5u<li><a>InappropriateType</a> The path refers to an existing
°5unon-directory object. <tt>[ENOTDIR]</tt></li>
°5u</ul>
listDirectory :: FilePath -> IO [FilePath]

-- | Similar to <a>listDirectory</a>, but always includes the special
°5uentries (<tt>.</tt> and <tt>..</tt>). (This applies to Windows as
°5uwell.)
°5u
°5uThe operation may fail with the same exceptions as
°5u<a>listDirectory</a>.
getDirectoryContents :: FilePath -> IO [FilePath]

-- | Obtain the current working directory as an absolute path.
°5u
°5uIn a multithreaded program, the current working directory is a global
°5ustate shared among all threads of the process. Therefore, when
°5uperforming filesystem operations from multiple threads, it is highly
°5urecommended to use absolute rather than relative paths (see:
°5u<tt>makeAbsolute</tt>).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><a>isDoesNotExistError</a> or <tt>NoSuchThing</tt> There is no
°5upath referring to the working directory. <tt>[EPERM, ENOENT,
°5uESTALE...]</tt></li>
°5u<li><a>isPermissionError</a> or <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation.
°5u<tt>[EACCES]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation.</li>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5ucurrent working directory.</li>
°5u</ul>
getCurrentDirectory :: IO FilePath

-- | Change the working directory to the given path.
°5u
°5uIn a multithreaded program, the current working directory is a global
°5ustate shared among all threads of the process. Therefore, when
°5uperforming filesystem operations from multiple threads, it is highly
°5urecommended to use absolute rather than relative paths (see:
°5u<a>makeAbsolute</a>).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> The operand is not a valid directory
°5uname. <tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> or <tt>NoSuchThing</tt> The directory
°5udoes not exist. <tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> or <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation.
°5u<tt>[EACCES]</tt></li>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5ucurrent working directory, or the working directory cannot be
°5udynamically changed.</li>
°5u<li><a>InappropriateType</a> The path refers to an existing
°5unon-directory object. <tt>[ENOTDIR]</tt></li>
°5u</ul>
setCurrentDirectory :: FilePath -> IO ()

-- | Run an <a>IO</a> action with the given working directory and restore
°5uthe original working directory afterwards, even if the given action
°5ufails due to an exception.
°5u
°5uThe operation may fail with the same exceptions as
°5u<a>getCurrentDirectory</a> and <a>setCurrentDirectory</a>.
withCurrentDirectory :: FilePath -> IO a -> IO a

-- | Returns the current user's home directory.
°5u
°5uThe directory returned is expected to be writable by the current user,
°5ubut note that it isn't generally considered good practice to store
°5uapplication-specific data here; use <a>getXdgDirectory</a> or
°5u<a>getAppUserDataDirectory</a> instead.
°5u
°5uOn Unix, <a>getHomeDirectory</a> returns the value of the
°5u<tt>HOME</tt> environment variable. On Windows, the system is queried
°5ufor a suitable path; a typical path might be
°5u<tt>C:/Users/<i>&lt;user&gt;</i></tt>.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5uhome directory.</li>
°5u<li><a>isDoesNotExistError</a> The home directory for the current user
°5udoes not exist, or cannot be found.</li>
°5u</ul>
getHomeDirectory :: IO FilePath

-- | Special directories for storing user-specific application data,
°5uconfiguration, and cache files, as specified by the <a>XDG Base
°5uDirectory Specification</a>.
°5u
°5uNote: On Windows, <a>XdgData</a> and <a>XdgConfig</a> map to the same
°5udirectory.
data XdgDirectory

-- | For data files (e.g. images). Defaults to <tt>~/.local/share</tt> and
°5ucan be overridden by the <tt>XDG_DATA_HOME</tt> environment variable.
°5uOn Windows, it is <tt>%APPDATA%</tt> (e.g.
°5u<tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming</tt>). Can be
°5uconsidered as the user-specific equivalent of <tt>/usr/share</tt>.
XdgData :: XdgDirectory

-- | For configuration files. Defaults to <tt>~/.config</tt> and can be
°5uoverridden by the <tt>XDG_CONFIG_HOME</tt> environment variable. On
°5uWindows, it is <tt>%APPDATA%</tt> (e.g.
°5u<tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming</tt>). Can be
°5uconsidered as the user-specific equivalent of <tt>/etc</tt>.
XdgConfig :: XdgDirectory

-- | For non-essential files (e.g. cache). Defaults to <tt>~/.cache</tt>
°5uand can be overridden by the <tt>XDG_CACHE_HOME</tt> environment
°5uvariable. On Windows, it is <tt>%LOCALAPPDATA%</tt> (e.g.
°5u<tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Local</tt>). Can be
°5uconsidered as the user-specific equivalent of <tt>/var/cache</tt>.
XdgCache :: XdgDirectory

-- | Obtain the paths to special directories for storing user-specific
°5uapplication data, configuration, and cache files, conforming to the
°5u<a>XDG Base Directory Specification</a>. Compared with
°5u<a>getAppUserDataDirectory</a>, this function provides a more
°5ufine-grained hierarchy as well as greater flexibility for the user.
°5u
°5uIt also works on Windows, although in that case <a>XdgData</a> and
°5u<a>XdgConfig</a> will map to the same directory.
°5u
°5uThe second argument is usually the name of the application. Since it
°5uwill be integrated into the path, it must consist of valid path
°5ucharacters.
°5u
°5uNote: The directory may not actually exist, in which case you would
°5uneed to create it with file mode <tt>700</tt> (i.e. only accessible by
°5uthe owner).
getXdgDirectory :: XdgDirectory -> FilePath -> IO FilePath

-- | Obtain the path to a special directory for storing user-specific
°5uapplication data (traditional Unix location). Newer applications may
°5uprefer the the XDG-conformant location provided by
°5u<a>getXdgDirectory</a> (<a>migration guide</a>).
°5u
°5uThe argument is usually the name of the application. Since it will be
°5uintegrated into the path, it must consist of valid path characters.
°5u
°5u<ul>
°5u<li>On Unix-like systems, the path is
°5u<tt>~/.<i>&lt;app&gt;</i></tt>.</li>
°5u<li>On Windows, the path is <tt>%APPDATA%/<i>&lt;app&gt;</i></tt>
°5u(e.g.
°5u<tt>C:/Users/<i>&lt;user&gt;</i>/AppData/Roaming/<i>&lt;app&gt;</i></tt>)</li>
°5u</ul>
°5u
°5uNote: the directory may not actually exist, in which case you would
°5uneed to create it. It is expected that the parent directory exists and
°5uis writable.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5uapplication-specific data directory.</li>
°5u<li><a>isDoesNotExistError</a> The home directory for the current user
°5udoes not exist, or cannot be found.</li>
°5u</ul>
getAppUserDataDirectory :: FilePath -> IO FilePath

-- | Returns the current user's document directory.
°5u
°5uThe directory returned is expected to be writable by the current user,
°5ubut note that it isn't generally considered good practice to store
°5uapplication-specific data here; use <a>getXdgDirectory</a> or
°5u<a>getAppUserDataDirectory</a> instead.
°5u
°5uOn Unix, <a>getUserDocumentsDirectory</a> returns the value of the
°5u<tt>HOME</tt> environment variable. On Windows, the system is queried
°5ufor a suitable path; a typical path might be
°5u<tt>C:/Users/<i>&lt;user&gt;</i>/Documents</tt>.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5udocument directory.</li>
°5u<li><a>isDoesNotExistError</a> The document directory for the current
°5uuser does not exist, or cannot be found.</li>
°5u</ul>
getUserDocumentsDirectory :: IO FilePath

-- | Returns the current directory for temporary files.
°5u
°5uOn Unix, <a>getTemporaryDirectory</a> returns the value of the
°5u<tt>TMPDIR</tt> environment variable or "/tmp" if the variable isn't
°5udefined. On Windows, the function checks for the existence of
°5uenvironment variables in the following order and uses the first path
°5ufound:
°5u
°5u<ul>
°5u<li>TMP environment variable.</li>
°5u<li>TEMP environment variable.</li>
°5u<li>USERPROFILE environment variable.</li>
°5u<li>The Windows directory</li>
°5u</ul>
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>UnsupportedOperation</a> The operating system has no notion of
°5utemporary directory.</li>
°5u</ul>
°5u
°5uThe function doesn't verify whether the path exists.
getTemporaryDirectory :: IO FilePath

-- | <a>removeFile</a> <i>file</i> removes the directory entry for an
°5uexisting file <i>file</i>, where <i>file</i> is not itself a
°5udirectory. The implementation may specify additional constraints which
°5umust be satisfied before a file can be removed (e.g. the file may not
°5ube in use by other processes).
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> The operand is not a valid file name.
°5u<tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The file does
°5unot exist. <tt>[ENOENT, ENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES, EPERM]</tt></li>
°5u<li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
°5uconstraints are not satisfied. <tt>[EBUSY]</tt></li>
°5u<li><a>InappropriateType</a> The operand refers to an existing
°5udirectory. <tt>[EPERM, EINVAL]</tt></li>
°5u</ul>
removeFile :: FilePath -> IO ()

-- | <tt><a>renameFile</a> old new</tt> changes the name of an existing
°5ufile system object from <i>old</i> to <i>new</i>. If the <i>new</i>
°5uobject already exists, it is atomically replaced by the <i>old</i>
°5uobject. Neither path may refer to an existing directory. A conformant
°5uimplementation need not support renaming files in all situations (e.g.
°5urenaming across different physical devices), but the constraints must
°5ube documented.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> Either operand is not a valid file name.
°5u<tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
°5ufile does not exist, or there is no path to the target. <tt>[ENOENT,
°5uENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES, EPERM]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
°5u<li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
°5uconstraints are not satisfied. <tt>[EBUSY]</tt></li>
°5u<li><a>UnsupportedOperation</a> The implementation does not support
°5urenaming in this situation. <tt>[EXDEV]</tt></li>
°5u<li><a>InappropriateType</a> Either path refers to an existing
°5udirectory. <tt>[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]</tt></li>
°5u</ul>
renameFile :: FilePath -> FilePath -> IO ()

-- | Rename a file or directory. If the destination path already exists, it
°5uis replaced atomically. The destination path must not point to an
°5uexisting directory. A conformant implementation need not support
°5urenaming files in all situations (e.g. renaming across different
°5uphysical devices), but the constraints must be documented.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><tt>HardwareFault</tt> A physical I/O error has occurred.
°5u<tt>[EIO]</tt></li>
°5u<li><tt>InvalidArgument</tt> Either operand is not a valid file name.
°5u<tt>[ENAMETOOLONG, ELOOP]</tt></li>
°5u<li><a>isDoesNotExistError</a> / <tt>NoSuchThing</tt> The original
°5ufile does not exist, or there is no path to the target. <tt>[ENOENT,
°5uENOTDIR]</tt></li>
°5u<li><a>isPermissionError</a> / <tt>PermissionDenied</tt> The process
°5uhas insufficient privileges to perform the operation. <tt>[EROFS,
°5uEACCES, EPERM]</tt></li>
°5u<li><tt>ResourceExhausted</tt> Insufficient resources are available to
°5uperform the operation. <tt>[EDQUOT, ENOSPC, ENOMEM, EMLINK]</tt></li>
°5u<li><tt>UnsatisfiedConstraints</tt> Implementation-dependent
°5uconstraints are not satisfied. <tt>[EBUSY]</tt></li>
°5u<li><a>UnsupportedOperation</a> The implementation does not support
°5urenaming in this situation. <tt>[EXDEV]</tt></li>
°5u<li><a>InappropriateType</a> Either the destination path refers to an
°5uexisting directory, or one of the parent segments in the destination
°5upath is not a directory. <tt>[ENOTDIR, EISDIR, EINVAL, EEXIST,
°5uENOTEMPTY]</tt></li>
°5u</ul>
renamePath :: FilePath -> FilePath -> IO ()

-- | Copy a file with its permissions. If the destination file already
°5uexists, it is replaced atomically. Neither path may refer to an
°5uexisting directory. No exceptions are thrown if the permissions could
°5unot be copied.
copyFile :: FilePath -> FilePath -> IO ()

-- | Copy a file with its associated metadata. If the destination file
°5ualready exists, it is overwritten. There is no guarantee of atomicity
°5uin the replacement of the destination file. Neither path may refer to
°5uan existing directory. If the source and/or destination are symbolic
°5ulinks, the copy is performed on the targets of the links.
°5u
°5uOn Windows, it behaves like the Win32 function <a>CopyFile</a>, which
°5ucopies various kinds of metadata including file attributes and
°5usecurity resource properties.
°5u
°5uOn Unix-like systems, permissions, access time, and modification time
°5uare preserved. If possible, the owner and group are also preserved.
°5uNote that the very act of copying can change the access time of the
°5usource file, hence the access times of the two files may differ after
°5uthe operation completes.
copyFileWithMetadata :: FilePath -> FilePath -> IO ()

-- | Obtain the size of a file in bytes.
getFileSize :: FilePath -> IO Integer

-- | Make a path absolute, <a>normalise</a> the path, and remove as many
°5uindirections from it as possible. Any trailing path separators are
°5udiscarded via <a>dropTrailingPathSeparator</a>. Additionally, on
°5uWindows the letter case of the path is canonicalized.
°5u
°5u<b>Note</b>: This function is a very big hammer. If you only need an
°5uabsolute path, <a>makeAbsolute</a> is sufficient for removing
°5udependence on the current working directory.
°5u
°5uIndirections include the two special directories <tt>.</tt> and
°5u<tt>..</tt>, as well as any symbolic links (and junction points on
°5uWindows). The input path need not point to an existing file or
°5udirectory. Canonicalization is performed on the longest prefix of the
°5upath that points to an existing file or directory. The remaining
°5uportion of the path that does not point to an existing file or
°5udirectory will still undergo <a>normalise</a>, but case
°5ucanonicalization and indirection removal are skipped as they are
°5uimpossible to do on a nonexistent path.
°5u
°5uMost programs should not worry about the canonicity of a path. In
°5uparticular, despite the name, the function does not truly guarantee
°5ucanonicity of the returned path due to the presence of hard links,
°5umount points, etc.
°5u
°5uIf the path points to an existing file or directory, then the output
°5upath shall also point to the same file or directory, subject to the
°5ucondition that the relevant parts of the file system do not change
°5uwhile the function is still running. In other words, the function is
°5udefinitively not atomic. The results can be utterly wrong if the
°5uportions of the path change while this function is running.
°5u
°5uSince some indirections (symbolic links on all systems, <tt>..</tt> on
°5unon-Windows systems, and junction points on Windows) are dependent on
°5uthe state of the existing filesystem, the function can only make a
°5uconservative attempt by removing such indirections from the longest
°5uprefix of the path that still points to an existing file or directory.
°5u
°5uNote that on Windows parent directories <tt>..</tt> are always fully
°5uexpanded before the symbolic links, as consistent with the rest of the
°5uWindows API (such as <tt>GetFullPathName</tt>). In contrast, on POSIX
°5usystems parent directories <tt>..</tt> are expanded alongside symbolic
°5ulinks from left to right. To put this more concretely: if <tt>L</tt>
°5uis a symbolic link for <tt>R/P</tt>, then on Windows <tt>L\..</tt>
°5urefers to <tt>.</tt>, whereas on other operating systems <tt>L/..</tt>
°5urefers to <tt>R</tt>.
°5u
°5uSimilar to <a>normalise</a>, passing an empty path is equivalent to
°5upassing the current directory.
°5u
°5u<tt>canonicalizePath</tt> can resolve at least 64 indirections in a
°5usingle path, more than what is supported by most operating systems.
°5uTherefore, it may return the fully resolved path even though the
°5uoperating system itself would have long given up.
°5u
°5uOn Windows XP or earlier systems, junction expansion is not performed
°5udue to their lack of <tt>GetFinalPathNameByHandle</tt>.
°5u
°5u<i>Changes since 1.2.3.0:</i> The function has been altered to be more
°5urobust and has the same exception behavior as <a>makeAbsolute</a>.
°5u
°5u<i>Changes since 1.3.0.0:</i> The function no longer preserves the
°5utrailing path separator. File symbolic links that appear in the middle
°5uof a path are properly dereferenced. Case canonicalization and
°5usymbolic link expansion are now performed on Windows.
canonicalizePath :: FilePath -> IO FilePath

-- | Convert a path into an absolute path. If the given path is relative,
°5uthe current directory is prepended and then the combined result is
°5u<a>normalise</a>d. If the path is already absolute, the path is simply
°5u<a>normalise</a>d. The function preserves the presence or absence of
°5uthe trailing path separator unless the path refers to the root
°5udirectory <tt>/</tt>.
°5u
°5uIf the path is already absolute, the operation never fails. Otherwise,
°5uthe operation may fail with the same exceptions as
°5u<a>getCurrentDirectory</a>.
makeAbsolute :: FilePath -> IO FilePath

-- | Construct a path relative to the current directory, similar to
°5u<a>makeRelative</a>.
°5u
°5uThe operation may fail with the same exceptions as
°5u<a>getCurrentDirectory</a>.
makeRelativeToCurrentDirectory :: FilePath -> IO FilePath

-- | Test whether the given path points to an existing filesystem object.
°5uIf the user lacks necessary permissions to search the parent
°5udirectories, this function may return false even if the file does
°5uactually exist.
doesPathExist :: FilePath -> IO Bool

-- | The operation <a>doesFileExist</a> returns <a>True</a> if the argument
°5ufile exists and is not a directory, and <a>False</a> otherwise.
doesFileExist :: FilePath -> IO Bool

-- | The operation <a>doesDirectoryExist</a> returns <a>True</a> if the
°5uargument file exists and is either a directory or a symbolic link to a
°5udirectory, and <a>False</a> otherwise.
doesDirectoryExist :: FilePath -> IO Bool

-- | Given the name or path of an executable file, <a>findExecutable</a>
°5usearches for such a file in a list of system-defined locations, which
°5ugenerally includes <tt>PATH</tt> and possibly more. The full path to
°5uthe executable is returned if found. For example, <tt>(findExecutable
°5u"ghc")</tt> would normally give you the path to GHC.
°5u
°5uThe path returned by <tt><a>findExecutable</a> name</tt> corresponds
°5uto the program that would be executed by <a>createProcess</a> when
°5upassed the same string (as a <tt>RawCommand</tt>, not a
°5u<tt>ShellCommand</tt>), provided that <tt>name</tt> is not a relative
°5upath with more than one segment.
°5u
°5uOn Windows, <a>findExecutable</a> calls the Win32 function
°5u<tt><a>SearchPath</a></tt>, which may search other places before
°5uchecking the directories in the <tt>PATH</tt> environment variable.
°5uWhere it actually searches depends on registry settings, but notably
°5uincludes the directory containing the current executable.
°5u
°5uOn non-Windows platforms, the behavior is equivalent to
°5u<a>findFileWith</a> using the search directories from the
°5u<tt>PATH</tt> environment variable and testing each file for
°5uexecutable permissions. Details can be found in the documentation of
°5u<a>findFileWith</a>.
findExecutable :: String -> IO (Maybe FilePath)

-- | Search for executable files in a list of system-defined locations,
°5uwhich generally includes <tt>PATH</tt> and possibly more.
°5u
°5uOn Windows, this <i>only returns the first ocurrence</i>, if any. Its
°5ubehavior is therefore equivalent to <a>findExecutable</a>.
°5u
°5uOn non-Windows platforms, the behavior is equivalent to
°5u<a>findExecutablesInDirectories</a> using the search directories from
°5uthe <tt>PATH</tt> environment variable. Details can be found in the
°5udocumentation of <a>findExecutablesInDirectories</a>.
findExecutables :: String -> IO [FilePath]

-- | Given a name or path, <a>findExecutable</a> appends the
°5u<a>exeExtension</a> to the query and searches for executable files in
°5uthe list of given search directories and returns all occurrences.
°5u
°5uThe behavior is equivalent to <a>findFileWith</a> using the given
°5usearch directories and testing each file for executable permissions.
°5uDetails can be found in the documentation of <a>findFileWith</a>.
°5u
°5uUnlike other similarly named functions,
°5u<a>findExecutablesInDirectories</a> does not use <tt>SearchPath</tt>
°5ufrom the Win32 API. The behavior of this function on Windows is
°5utherefore equivalent to those on non-Windows platforms.
findExecutablesInDirectories :: [FilePath] -> String -> IO [FilePath]

-- | Search through the given list of directories for the given file.
°5u
°5uThe behavior is equivalent to <a>findFileWith</a>, returning only the
°5ufirst occurrence. Details can be found in the documentation of
°5u<a>findFileWith</a>.
findFile :: [FilePath] -> String -> IO (Maybe FilePath)

-- | Search through the given list of directories for the given file and
°5ureturns all paths where the given file exists.
°5u
°5uThe behavior is equivalent to <a>findFilesWith</a>. Details can be
°5ufound in the documentation of <a>findFilesWith</a>.
findFiles :: [FilePath] -> String -> IO [FilePath]

-- | Search through a given list of directories for a file that has the
°5ugiven name and satisfies the given predicate and return the path of
°5uthe first occurrence. The directories are checked in a left-to-right
°5uorder.
°5u
°5uThis is essentially a more performant version of <a>findFilesWith</a>
°5uthat always returns the first result, if any. Details can be found in
°5uthe documentation of <a>findFilesWith</a>.
findFileWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO (Maybe FilePath)

-- | <tt>findFilesWith predicate dirs name</tt> searches through the list
°5uof directories (<tt>dirs</tt>) for files that have the given
°5u<tt>name</tt> and satisfy the given <tt>predicate</tt> ands return the
°5upaths of those files. The directories are checked in a left-to-right
°5uorder and the paths are returned in the same order.
°5u
°5uIf the <tt>name</tt> is a relative path, then for every search
°5udirectory <tt>dir</tt>, the function checks whether <tt>dir
°5u<a>&lt;/&gt;</a> name</tt> exists and satisfies the predicate. If so,
°5u<tt>dir <a>&lt;/&gt;</a> name</tt> is returned as one of the results.
°5uIn other words, the returned paths can be either relative or absolute
°5udepending on the search directories were used. If there are no search
°5udirectories, no results are ever returned.
°5u
°5uIf the <tt>name</tt> is an absolute path, then the function will
°5ureturn a single result if the file exists and satisfies the predicate
°5uand no results otherwise. This is irrespective of what search
°5udirectories were given.
findFilesWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO [FilePath]

-- | Filename extension for executable files (including the dot if any)
°5u(usually <tt>""</tt> on POSIX systems and <tt>".exe"</tt> on Windows
°5uor OS/2).
exeExtension :: String

-- | Create a <i>file</i> symbolic link. The target path can be either
°5uabsolute or relative and need not refer to an existing file. The order
°5uof arguments follows the POSIX convention.
°5u
°5uTo remove an existing file symbolic link, use <a>removeFile</a>.
°5u
°5uAlthough the distinction between <i>file</i> symbolic links and
°5u<i>directory</i> symbolic links does not exist on POSIX systems, on
°5uWindows this is an intrinsic property of every symbolic link and
°5ucannot be changed without recreating the link. A file symbolic link
°5uthat actually points to a directory will fail to dereference and vice
°5uversa. Moreover, creating symbolic links on Windows requires
°5uprivileges normally unavailable to users outside the Administrators
°5ugroup. Portable programs that use symbolic links should take both into
°5uconsideration.
°5u
°5uOn Windows, the function is implemented using
°5u<tt>CreateSymbolicLink</tt> with <tt>dwFlags</tt> set to zero. On
°5uPOSIX, the function uses <tt>symlink</tt> and is therefore atomic.
°5u
°5uWindows-specific errors: This operation may fail with
°5u<a>permissionErrorType</a> if the user lacks the privileges to create
°5usymbolic links. It may also fail with <a>illegalOperationErrorType</a>
°5uif the file system does not support symbolic links.
createFileLink :: FilePath -> FilePath -> IO ()

-- | Create a <i>directory</i> symbolic link. The target path can be either
°5uabsolute or relative and need not refer to an existing directory. The
°5uorder of arguments follows the POSIX convention.
°5u
°5uTo remove an existing directory symbolic link, use
°5u<a>removeDirectoryLink</a>.
°5u
°5uAlthough the distinction between <i>file</i> symbolic links and
°5u<i>directory</i> symbolic links does not exist on POSIX systems, on
°5uWindows this is an intrinsic property of every symbolic link and
°5ucannot be changed without recreating the link. A file symbolic link
°5uthat actually points to a directory will fail to dereference and vice
°5uversa. Moreover, creating symbolic links on Windows requires
°5uprivileges normally unavailable to users outside the Administrators
°5ugroup. Portable programs that use symbolic links should take both into
°5uconsideration.
°5u
°5uOn Windows, the function is implemented using
°5u<tt>CreateSymbolicLink</tt> with <tt>dwFlags</tt> set to
°5u<tt>SYMBOLIC_LINK_FLAG_DIRECTORY</tt>. On POSIX, this is an alias for
°5u<a>createFileLink</a> and is therefore atomic.
°5u
°5uWindows-specific errors: This operation may fail with
°5u<a>permissionErrorType</a> if the user lacks the privileges to create
°5usymbolic links. It may also fail with <a>illegalOperationErrorType</a>
°5uif the file system does not support symbolic links.
createDirectoryLink :: FilePath -> FilePath -> IO ()

-- | Remove an existing <i>directory</i> symbolic link.
°5u
°5uOn Windows, this is an alias for <a>removeDirectory</a>. On POSIX
°5usystems, this is an alias for <a>removeFile</a>.
°5u
°5uSee also: <a>removeFile</a>, which can remove an existing <i>file</i>
°5usymbolic link.
removeDirectoryLink :: FilePath -> IO ()

-- | Check whether the path refers to a symbolic link. An exception is
°5uthrown if the path does not exist or is inaccessible.
°5u
°5uOn Windows, this checks for <tt>FILE_ATTRIBUTE_REPARSE_POINT</tt>. In
°5uaddition to symbolic links, the function also returns true on junction
°5upoints. On POSIX systems, this checks for <tt>S_IFLNK</tt>.
pathIsSymbolicLink :: FilePath -> IO Bool

-- | Retrieve the target path of either a file or directory symbolic link.
°5uThe returned path may not be absolute, may not exist, and may not even
°5ube a valid path.
°5u
°5uOn Windows systems, this calls <tt>DeviceIoControl</tt> with
°5u<tt>FSCTL_GET_REPARSE_POINT</tt>. In addition to symbolic links, the
°5ufunction also works on junction points. On POSIX systems, this calls
°5u<tt>readlink</tt>.
°5u
°5uWindows-specific errors: This operation may fail with
°5u<a>illegalOperationErrorType</a> if the file system does not support
°5usymbolic links.
getSymbolicLinkTarget :: FilePath -> IO FilePath
data Permissions
emptyPermissions :: Permissions
readable :: Permissions -> Bool
writable :: Permissions -> Bool
executable :: Permissions -> Bool
searchable :: Permissions -> Bool
setOwnerReadable :: Bool -> Permissions -> Permissions
setOwnerWritable :: Bool -> Permissions -> Permissions
setOwnerExecutable :: Bool -> Permissions -> Permissions
setOwnerSearchable :: Bool -> Permissions -> Permissions

-- | Get the permissions of a file or directory.
°5u
°5uOn Windows, the <a>writable</a> permission corresponds to the
°5u"read-only" attribute. The <a>executable</a> permission is set if the
°5ufile extension is of an executable file type. The <a>readable</a>
°5upermission is always set.
°5u
°5uOn POSIX systems, this returns the result of <tt>access</tt>.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to access
°5uthe permissions, or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
getPermissions :: FilePath -> IO Permissions

-- | Set the permissions of a file or directory.
°5u
°5uOn Windows, this is only capable of changing the <a>writable</a>
°5upermission, which corresponds to the "read-only" attribute. Changing
°5uthe other permissions has no effect.
°5u
°5uOn POSIX systems, this sets the <i>owner</i> permissions.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to set the
°5upermissions, or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
setPermissions :: FilePath -> Permissions -> IO ()

-- | Copy the permissions of one file to another. This reproduces the
°5upermissions more accurately than using <a>getPermissions</a> followed
°5uby <a>setPermissions</a>.
°5u
°5uOn Windows, this copies only the read-only attribute.
°5u
°5uOn POSIX systems, this is equivalent to <tt>stat</tt> followed by
°5u<tt>chmod</tt>.
copyPermissions :: FilePath -> FilePath -> IO ()

-- | Obtain the time at which the file or directory was last accessed.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to read the
°5uaccess time; or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
°5u
°5uCaveat for POSIX systems: This function returns a timestamp with
°5usub-second resolution only if this package is compiled against
°5u<tt>unix-2.6.0.0</tt> or later and the underlying filesystem supports
°5uthem.
getAccessTime :: FilePath -> IO UTCTime

-- | Obtain the time at which the file or directory was last modified.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to read the
°5umodification time; or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
°5u
°5uCaveat for POSIX systems: This function returns a timestamp with
°5usub-second resolution only if this package is compiled against
°5u<tt>unix-2.6.0.0</tt> or later and the underlying filesystem supports
°5uthem.
getModificationTime :: FilePath -> IO UTCTime

-- | Change the time at which the file or directory was last accessed.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to alter the
°5uaccess time; or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
°5u
°5uSome caveats for POSIX systems:
°5u
°5u<ul>
°5u<li>Not all systems support <tt>utimensat</tt>, in which case the
°5ufunction can only emulate the behavior by reading the modification
°5utime and then setting both the access and modification times together.
°5uOn systems where <tt>utimensat</tt> is supported, the access time is
°5uset atomically with nanosecond precision.</li>
°5u<li>If compiled against a version of <tt>unix</tt> prior to
°5u<tt>2.7.0.0</tt>, the function would not be able to set timestamps
°5uwith sub-second resolution. In this case, there would also be loss of
°5uprecision in the modification time.</li>
°5u</ul>
setAccessTime :: FilePath -> UTCTime -> IO ()

-- | Change the time at which the file or directory was last modified.
°5u
°5uThe operation may fail with:
°5u
°5u<ul>
°5u<li><a>isPermissionError</a> if the user is not permitted to alter the
°5umodification time; or</li>
°5u<li><a>isDoesNotExistError</a> if the file or directory does not
°5uexist.</li>
°5u</ul>
°5u
°5uSome caveats for POSIX systems:
°5u
°5u<ul>
°5u<li>Not all systems support <tt>utimensat</tt>, in which case the
°5ufunction can only emulate the behavior by reading the access time and
°5uthen setting both the access and modification times together. On
°5usystems where <tt>utimensat</tt> is supported, the modification time
°5uis set atomically with nanosecond precision.</li>
°5u<li>If compiled against a version of <tt>unix</tt> prior to
°5u<tt>2.7.0.0</tt>, the function would not be able to set timestamps
°5uwith sub-second resolution. In this case, there would also be loss of
°5uprecision in the access time.</li>
°5u</ul>
setModificationTime :: FilePath -> UTCTime -> IO ()

-- | <i>Deprecated: Use <a>pathIsSymbolicLink</a> instead</i>
isSymbolicLink :: FilePath -> IO Bool
instance GHC.Show.Show System.Directory.XdgDirectory
instance GHC.Read.Read System.Directory.XdgDirectory
instance GHC.Classes.Ord System.Directory.XdgDirectory
instance GHC.Classes.Eq System.Directory.XdgDirectory
instance GHC.Enum.Enum System.Directory.XdgDirectory
instance GHC.Enum.Bounded System.Directory.XdgDirectory
