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


-- | Platform-agnostic library for filesystem operations
--   
--   This library provides a basic set of operations for manipulating files
--   and directories in a portable way.
@package directory
@version 1.3.3.0


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

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

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

-- | Creates a new thread to run the <a>IO</a> computation passed as the
--   first argument, and returns the <a>ThreadId</a> of the newly created
--   thread.
--   
--   The new thread will be a lightweight, <i>unbound</i> thread. Foreign
--   calls made by this thread are not guaranteed to be made by any
--   particular OS thread; if you need foreign calls to be made by a
--   particular OS thread, then use <a>forkOS</a> instead.
--   
--   The new thread inherits the <i>masked</i> state of the parent (see
--   <a>mask</a>).
--   
--   The newly created thread has an exception handler that discards the
--   exceptions <a>BlockedIndefinitelyOnMVar</a>,
--   <a>BlockedIndefinitelyOnSTM</a>, and <a>ThreadKilled</a>, and passes
--   all 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,
--   <a>putMVar</a> will wait until it becomes empty.
--   
--   There are two further important properties of <a>putMVar</a>:
--   
--   <ul>
--   <li><a>putMVar</a> is single-wakeup. That is, if there are multiple
--   threads blocked in <a>putMVar</a>, and the <a>MVar</a> becomes empty,
--   only one thread will be woken up. The runtime guarantees that the
--   woken thread completes its <a>putMVar</a> operation.</li>
--   <li>When multiple threads are blocked on an <a>MVar</a>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using <a>MVar</a>s.</li>
--   </ul>
putMVar :: () => MVar a -> a -> IO ()

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

-- | Return the contents of the <a>MVar</a>. If the <a>MVar</a> is
--   currently empty, <a>takeMVar</a> will wait until it is full. After a
--   <a>takeMVar</a>, the <a>MVar</a> is left empty.
--   
--   There are two further important properties of <a>takeMVar</a>:
--   
--   <ul>
--   <li><a>takeMVar</a> is single-wakeup. That is, if there are multiple
--   threads blocked in <a>takeMVar</a>, and the <a>MVar</a> becomes full,
--   only one thread will be woken up. The runtime guarantees that the
--   woken thread completes its <a>takeMVar</a> operation.</li>
--   <li>When multiple threads are blocked on an <a>MVar</a>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using <a>MVar</a>s.</li>
--   </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
--   computation 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
--   afterward.
finally :: () => IO a -> IO b -> IO a

-- | When you want to acquire a resource, do some work with it, and then
--   release the resource, it is a good idea to use <a>bracket</a>, because
--   <a>bracket</a> will install the necessary exception handler to release
--   the resource in the event that an exception is raised during the
--   computation. If an exception is raised, then <a>bracket</a> will
--   re-raise the exception (after performing the release).
--   
--   A common example is opening a file:
--   
--   <pre>
--   bracket
--     (openFile "filename" ReadMode)
--     (hClose)
--     (\fileHandle -&gt; do { ... })
--   </pre>
--   
--   The arguments to <a>bracket</a> are in this order so that we can
--   partially apply it, e.g.:
--   
--   <pre>
--   withFile name mode = bracket (openFile name mode) hClose
--   </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
--   an 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
--   <tt>(<a>Right</a> a)</tt> if no exception of type <tt>e</tt> was
--   raised, or <tt>(<a>Left</a> ex)</tt> if an exception of type
--   <tt>e</tt> was raised and its value is <tt>ex</tt>. If any other type
--   of exception is raised than it will be propogated up to the next
--   enclosing exception handler.
--   
--   <pre>
--   try a = catch (Right `liftM` a) (return . Left)
--   </pre>
try :: Exception e => IO a -> IO (Either e a)

-- | Executes an IO computation with asynchronous exceptions <i>masked</i>.
--   That is, any thread which attempts to raise an exception in the
--   current thread with <a>throwTo</a> will be blocked until asynchronous
--   exceptions are unmasked again.
--   
--   The argument passed to <a>mask</a> is a function that takes as its
--   argument another function, which can be used to restore the prevailing
--   masking state within the context of the masked computation. For
--   example, a common way to use <a>mask</a> is to protect the acquisition
--   of a resource:
--   
--   <pre>
--   mask $ \restore -&gt; do
--       x &lt;- acquire
--       restore (do_something_with x) `onException` release
--       release
--   </pre>
--   
--   This code guarantees that <tt>acquire</tt> is paired with
--   <tt>release</tt>, by masking asynchronous exceptions for the critical
--   parts. (Rather than write this code yourself, it would be better to
--   use <a>bracket</a> which abstracts the general pattern).
--   
--   Note that the <tt>restore</tt> action passed to the argument to
--   <a>mask</a> does not necessarily unmask asynchronous exceptions, it
--   just restores the masking state to that of the enclosing context. Thus
--   if asynchronous exceptions are already masked, <a>mask</a> cannot be
--   used to unmask exceptions again. This is so that if you call a library
--   function with exceptions masked, you can be sure that the library call
--   will not be able to unmask exceptions again. If you are writing
--   library code and need to use asynchronous exceptions, the only way is
--   to create a new thread; see <a>forkIOWithUnmask</a>.
--   
--   Asynchronous exceptions may still be received while in the masked
--   state if the masked thread <i>blocks</i> in certain ways; see
--   <a>Control.Exception#interruptible</a>.
--   
--   Threads created by <a>forkIO</a> inherit the <a>MaskingState</a> from
--   the parent; that is, to start a thread in the
--   <a>MaskedInterruptible</a> state, use <tt>mask_ $ forkIO ...</tt>.
--   This is particularly useful if you need to establish an exception
--   handler in the forked thread before any asynchronous exceptions are
--   received. To create a new thread in an unmasked state use
--   <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>
--   monad.
--   
--   Although <a>throwIO</a> has a type that is an instance of the type of
--   <a>throw</a>, the two functions are subtly different:
--   
--   <pre>
--   throw e   `seq` x  ===&gt; throw e
--   throwIO e `seq` x  ===&gt; x
--   </pre>
--   
--   The first example will cause the exception <tt>e</tt> to be raised,
--   whereas the second one won't. In fact, <a>throwIO</a> will only cause
--   an exception to be raised when it is used within the <a>IO</a> monad.
--   The <a>throwIO</a> variant should be used in preference to
--   <a>throw</a> to raise an exception within the <a>IO</a> monad because
--   it guarantees ordering with respect to other <a>IO</a> operations,
--   whereas <a>throw</a> does not.
throwIO :: Exception e => e -> IO a

-- | This is the simplest of the exception-catching functions. It takes a
--   single argument, runs it, and if an exception is raised the "handler"
--   is executed, with the value of the exception passed as an argument.
--   Otherwise, the result is returned as normal. For example:
--   
--   <pre>
--   catch (readFile f)
--         (\e -&gt; do let err = show (e :: IOException)
--                   hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
--                   return "")
--   </pre>
--   
--   Note that we have to give a type signature to <tt>e</tt>, or the
--   program will not typecheck as the type is ambiguous. While it is
--   possible to catch exceptions of any type, see the section "Catching
--   all exceptions" (in <a>Control.Exception</a>) for an explanation of
--   the problems with doing so.
--   
--   For catching exceptions in pure (non-<a>IO</a>) expressions, see the
--   function <a>evaluate</a>.
--   
--   Note that due to Haskell's unspecified evaluation order, an expression
--   may throw one of several possible exceptions: consider the expression
--   <tt>(error "urk") + (1 `div` 0)</tt>. Does the expression throw
--   <tt>ErrorCall "urk"</tt>, or <tt>DivideByZero</tt>?
--   
--   The answer is "it might throw either"; the choice is
--   non-deterministic. If you are catching any type of exception then you
--   might catch either. If you are calling <tt>catch</tt> with type <tt>IO
--   Int -&gt; (ArithException -&gt; IO Int) -&gt; IO Int</tt> then the
--   handler may get run with <tt>DivideByZero</tt> as an argument, or an
--   <tt>ErrorCall "urk"</tt> exception may be propogated further up. If
--   you call it again, you might get a the opposite behaviour. This is ok,
--   because <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
--   hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
--   scenes 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 composition of Kleisli arrows.
--   <tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped.
--   
--   Note how this operator resembles function composition
--   <tt>(<a>.</a>)</tt>:
--   
--   <pre>
--   (.)   ::            (b -&gt;   c) -&gt; (a -&gt;   b) -&gt; a -&gt;   c
--   (&lt;=&lt;) :: Monad m =&gt; (b -&gt; m c) -&gt; (a -&gt; m b) -&gt; a -&gt; m c
--   </pre>
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
infixr 1 <=<

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

-- | Conditional execution of <a>Applicative</a> expressions. For example,
--   
--   <pre>
--   when debug (putStrLn "Debugging")
--   </pre>
--   
--   will output the string <tt>Debugging</tt> if the Boolean value
--   <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
--   other character is returned unchanged.
toUpper :: Char -> Char

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

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

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

-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
--   version that doesn't ignore the results see <a>for</a>.
--   
--   <pre>
--   &gt;&gt;&gt; for_ [1..4] print
--   1
--   2
--   3
--   4
--   </pre>
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()

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

-- | <tt><a>on</a> b u x y</tt> runs the binary function <tt>b</tt>
--   <i>on</i> the results of applying unary function <tt>u</tt> to two
--   arguments <tt>x</tt> and <tt>y</tt>. From the opposite perspective, it
--   transforms two inputs and combines the outputs.
--   
--   <pre>
--   ((+) `<a>on</a>` f) x y = f x + f y
--   </pre>
--   
--   Typical usage: <tt><a>sortBy</a> (<tt>compare</tt> `on`
--   <tt>fst</tt>)</tt>.
--   
--   Algebraic properties:
--   
--   <ul>
--   <li><pre>(*) `on` <a>id</a> = (*) -- (if (*) ∉ {⊥, <a>const</a>
--   ⊥})</pre></li>
--   <li><pre>((*) `on` f) `on` g = (*) `on` (f . g)</pre></li>
--   <li><pre><a>flip</a> on f . <a>flip</a> on g = <a>flip</a> on (g .
--   f)</pre></li>
--   </ul>
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
--   returns a list of all the <a>Just</a> values.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; catMaybes [Just 1, Nothing, Just 3]
--   [1,3]
--   </pre>
--   
--   When constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
--   be used to return all of the "success" results (if the list is the
--   result of a <a>map</a>, then <a>mapMaybe</a> would be more
--   appropriate):
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [Just 1,Nothing,Just 3]
--   
--   &gt;&gt;&gt; catMaybes $ [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [1,3]
--   </pre>
catMaybes :: () => [Maybe a] -> [a]

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

-- | The <a>fromMaybe</a> function takes a default value and and
--   <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
--   the default values; otherwise, it returns the value contained in the
--   <a>Maybe</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" Nothing
--   ""
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
--   5
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "")
--   0
--   </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.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized 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
--   version 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
--   object, or an array of objects, which may be marshalled to or from
--   Haskell values of type <tt>a</tt>.
--   
--   The type <tt>a</tt> will often be an instance of class <a>Storable</a>
--   which provides the marshalling operations. However this is not
--   essential, and you can provide your own operations to access the
--   pointer. For example you might write small foreign functions to get or
--   set the fields of a C <tt>struct</tt>.
data Ptr a

-- | Temporarily store a list of storable values in memory (like
--   <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
--   <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
--   wrapped into a <a>Maybe</a>, using <a>nullPtr</a> to represent
--   <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>,
--   passing as argument a pointer to a temporarily allocated block of
--   memory into which <tt>val</tt> has been marshalled (the combination of
--   <a>alloca</a> and <a>poke</a>).
--   
--   The memory is freed when <tt>f</tt> terminates (either normally or via
--   an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
--   used 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>,
--   passing as argument a pointer to a temporarily allocated block of
--   memory of <tt>n</tt> bytes. The block of memory is sufficiently
--   aligned for any of the basic foreign types that fits into a memory
--   block of the allocated size.
--   
--   The memory is freed when <tt>f</tt> terminates (either normally or via
--   an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
--   used after this.
allocaBytes :: () => Int -> (Ptr a -> IO b) -> IO b

-- | <tt><a>alloca</a> f</tt> executes the computation <tt>f</tt>, passing
--   as argument a pointer to a temporarily allocated block of memory
--   sufficient to hold values of type <tt>a</tt>.
--   
--   The memory is freed when <tt>f</tt> terminates (either normally or via
--   an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be
--   used after this.
alloca :: Storable a => (Ptr a -> IO b) -> IO b

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

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

-- | Computes the alignment constraint of the argument. An alignment
--   constraint <tt>x</tt> is fulfilled by any address divisible by
--   <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
--   same kind. The first argument specifies the start address of the array
--   and the second the index into the array (the first element of the
--   array has index <tt>0</tt>). The following equality holds,
--   
--   <pre>
--   peekElemOff addr idx = IOExts.fixIO $ \result -&gt;
--     peek (addr `plusPtr` (idx * sizeOf result))
--   </pre>
--   
--   Note that this is only a specification, not necessarily the concrete
--   implementation 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
--   same kind. The following equality holds:
--   
--   <pre>
--   pokeElemOff addr idx x = 
--     poke (addr `plusPtr` (idx * sizeOf x)) x
--   </pre>
pokeElemOff :: Storable a => Ptr a -> Int -> a -> IO ()

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

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

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

-- | Write the given value to the given memory location. Alignment
--   restrictions 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
--   <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
--   when appropriate.
throwErrnoPathIfMinus1_ :: (Eq a, Num a) => String -> FilePath -> IO a -> IO ()

-- | Throw an <a>IOException</a> corresponding to the current value of
--   <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
--   temporary storage.
--   
--   <ul>
--   <li>the Haskell string may <i>not</i> contain any NUL characters</li>
--   <li>the memory is freed when the subcomputation terminates (either
--   normally or via an exception), so the pointer to the temporary storage
--   must <i>not</i> be used after this.</li>
--   </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
--   temporary storage.
--   
--   <ul>
--   <li>the Haskell string may <i>not</i> contain any NUL characters</li>
--   <li>the memory is freed when the subcomputation terminates (either
--   normally or via an exception), so the pointer to the temporary storage
--   must <i>not</i> be used after this.</li>
--   </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
--   NUL.
type CString = Ptr CChar

-- | A C wide string is a reference to an array of C wide characters
--   terminated 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
--   undecodable bytes to be round-tripped through it.
--   
--   This <a>TextEncoding</a> is used to decode and encode command line
--   arguments and environment variables on non-Windows platforms.
--   
--   On Windows, this encoding *should not* be used if possible because the
--   use of code pages is deprecated: Strings should be retrieved via the
--   "wide" W-family of UTF-16 APIs instead
getFileSystemEncoding :: IO TextEncoding

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

-- | Return the value of the environment variable <tt>var</tt>, or
--   <tt>Nothing</tt> if there is no such value.
--   
--   For POSIX users, this is equivalent to <a>getEnv</a>.
lookupEnv :: String -> IO (Maybe String)

-- | Computation <a>getEnv</a> <tt>var</tt> returns the value of the
--   environment variable <tt>var</tt>. For the inverse, the <a>setEnv</a>
--   function can be used.
--   
--   This computation may fail with:
--   
--   <ul>
--   <li><a>isDoesNotExistError</a> if the environment variable does not
--   exist.</li>
--   </ul>
getEnv :: String -> IO String

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

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

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

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

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

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

-- | <a>hGetBuf</a> <tt>hdl buf count</tt> reads data from the handle
--   <tt>hdl</tt> into the buffer <tt>buf</tt> until either EOF is reached
--   or <tt>count</tt> 8-bit bytes have been read. It returns the number of
--   bytes actually read. This may be zero if EOF was reached before any
--   data was read (or if <tt>count</tt> is zero).
--   
--   <a>hGetBuf</a> never raises an EOF exception, instead it returns a
--   value smaller than <tt>count</tt>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <a>hGetBuf</a> will behave as if EOF was reached.
--   
--   <a>hGetBuf</a> ignores the prevailing <tt>TextEncoding</tt> and
--   <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
--   bytes from the buffer <tt>buf</tt> to the handle <tt>hdl</tt>. It
--   returns ().
--   
--   <a>hPutBuf</a> ignores any text encoding that applies to the
--   <a>Handle</a>, writing the bytes directly to the underlying file or
--   device.
--   
--   <a>hPutBuf</a> ignores the prevailing <tt>TextEncoding</tt> and
--   <a>NewlineMode</a> on the <a>Handle</a>, and writes bytes directly.
--   
--   This operation may fail with:
--   
--   <ul>
--   <li><a>ResourceVanished</a> if the handle is a pipe or socket, and the
--   reading end is closed. (If this is a POSIX system, and the program has
--   not asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead,
--   whose default action is to terminate the program).</li>
--   </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>
--   to the file or channel managed by <tt>hdl</tt>.
--   
--   This operation may fail with:
--   
--   <ul>
--   <li><a>isFullError</a> if the device is full; or</li>
--   <li><a>isPermissionError</a> if another system resource limit would be
--   exceeded.</li>
--   </ul>
hPutStr :: Handle -> String -> IO ()

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

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

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> when first allocated. Once
--   it is closed it can no longer be used for either input or output,
--   though an implementation cannot re-use its storage while references
--   remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
--   The string produced by showing a handle is system dependent; it should
--   include enough information to identify the handle for debugging. A
--   handle is equal according to <a>==</a> only to itself; no attempt is
--   made 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
--   any <a>IOException</a> raised in the action protected by
--   <a>catchIOError</a>. An <a>IOException</a> is caught by the most
--   recent handler established by one of the exception handling functions.
--   These handlers are not selective: all <a>IOException</a>s are caught.
--   Exception propagation must be explicitly provided in a handler by
--   re-raising any unwanted exceptions. For example, in
--   
--   <pre>
--   f = catchIOError g (\e -&gt; if IO.isEOFError e then return [] else ioError e)
--   </pre>
--   
--   the function <tt>f</tt> returns <tt>[]</tt> when an end-of-file
--   exception (cf. <a>isEOFError</a>) occurs in <tt>g</tt>; otherwise, the
--   exception is propagated to the next outer handler.
--   
--   When an exception propagates outside the main program, the Haskell
--   system prints the associated <a>IOException</a> value and exits the
--   program.
--   
--   Non-I/O exceptions are not caught by this variant; to catch all
--   exceptions, use <a>catch</a> from <a>Control.Exception</a>.
catchIOError :: () => IO a -> (IOError -> IO a) -> IO a

-- | Catch any <a>IOException</a> that occurs in the computation and throw
--   a modified 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
--   sufficient 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
--   user does not have sufficient operating system privilege to perform
--   that operation.
isPermissionError :: IOError -> Bool

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

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

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

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

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

-- | Construct an <a>IOException</a> value with a string describing the
--   error. The <a>fail</a> method of the <a>IO</a> instance of the
--   <a>Monad</a> class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOException</a> instead of returning a
--   result. For a more general type of exception, including also those
--   that arise in pure code, see <a>Exception</a>.
--   
--   In 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>
--   in case no result is available within <tt>n</tt> microseconds
--   (<tt>1/10^6</tt> seconds). In case a result is available before the
--   timeout expires, <tt>Just a</tt> is returned. A negative timeout
--   interval means "wait indefinitely". When specifying long timeouts, be
--   careful not to exceed <tt>maxBound :: Int</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; timeout 1000000 (threadDelay 1000 *&gt; pure "finished on time")
--   Just "finished on time"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; timeout 10000 (threadDelay 100000 *&gt; pure "finished on time")
--   Nothing
--   </pre>
--   
--   The design of this combinator was guided by the objective that
--   <tt>timeout n f</tt> should behave exactly the same as <tt>f</tt> as
--   long as <tt>f</tt> doesn't time out. This means that <tt>f</tt> has
--   the same <a>myThreadId</a> it would have without the timeout wrapper.
--   Any exceptions <tt>f</tt> might throw cancel the timeout and propagate
--   further up. It also possible for <tt>f</tt> to receive exceptions
--   thrown to it by another thread.
--   
--   A tricky implementation detail is the question of how to abort an
--   <tt>IO</tt> computation. This combinator relies on asynchronous
--   exceptions internally. The technique works very well for computations
--   executing inside of the Haskell runtime system, but it doesn't work at
--   all for non-Haskell code. Foreign function calls, for example, cannot
--   be timed out with this combinator simply because an arbitrary C
--   function cannot receive asynchronous exceptions. When <tt>timeout</tt>
--   is used to wrap an FFI call that blocks, no timeout event can be
--   delivered until the FFI call returns, which pretty much negates the
--   purpose of the combinator. In practice, however, this limitation is
--   less severe than it may sound. Standard I/O functions like
--   <a>hGetBuf</a>, <a>hPutBuf</a>, Network.Socket.accept, or
--   <a>hWaitForInput</a> appear to be blocking, but they really don't
--   because the runtime system uses scheduling mechanisms like
--   <tt>select(2)</tt> to perform asynchronous I/O, so it is possible to
--   interrupt standard socket I/O or file I/O using this combinator.
timeout :: () => Int -> IO a -> IO (Maybe a)

-- | Uninhabited data type
data Void


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

-- | A generator with side-effects.
newtype ListT m a
ListT :: m (Maybe (a, ListT m a)) -> ListT m a
[unListT] :: ListT m a -> m (Maybe (a, ListT m a))
emptyListT :: Applicative m => ListT m a
maybeToListT :: Applicative m => m (Maybe a) -> ListT m a
listToListT :: Applicative m => [a] -> ListT m a
liftJoinListT :: Monad m => m (ListT m a) -> ListT m a
listTHead :: Functor m => ListT m a -> m (Maybe a)
listTToList :: Monad m => ListT m a -> m [a]
andM :: Monad m => m Bool -> m Bool -> m Bool
sequenceWithIOErrors_ :: [IO ()] -> IO ()

-- | Similar to <a>try</a> but only catches a specify kind of
--   <a>IOError</a> as specified by the predicate.
tryIOErrorType :: (IOError -> Bool) -> IO a -> IO (Either IOError a)

-- | Attempt to perform the given action, silencing any IO exception thrown
--   by it.
ignoreIOExceptions :: IO () -> IO ()
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: directory link
DirectoryLink :: FileType

-- | Check whether the given <a>FileType</a> is considered a directory by
--   the operating system. This affects the choice of certain functions
--   e.g. <tt>removeDirectory</tt> vs <tt>removeFile</tt>.
fileTypeIsDirectory :: FileType -> Bool

-- | Return whether the given <a>FileType</a> is a link.
fileTypeIsLink :: FileType -> Bool
data Permissions
Permissions :: Bool -> Bool -> Bool -> Bool -> Permissions
[readable] :: Permissions -> Bool
[writable] :: Permissions -> Bool
[executable] :: Permissions -> Bool
[searchable] :: Permissions -> Bool

-- | Convert a path into an absolute path. If the given path is relative,
--   the current directory is prepended. If the path is already absolute,
--   the path is returned unchanged. The function preserves the presence or
--   absence of the trailing path separator.
--   
--   If the path is already absolute, the operation never fails. Otherwise,
--   the operation may fail with the same exceptions as
--   <tt>getCurrentDirectory</tt>.
--   
--   (internal API)
prependCurrentDirectoryWith :: IO FilePath -> FilePath -> IO FilePath

-- | Truncate the destination file and then copy the contents of the source
--   file to the destination file. If the destination file already exists,
--   its attributes shall remain unchanged. Otherwise, its attributes are
--   reset to the defaults.
copyFileContents :: FilePath -> FilePath -> IO ()

-- | Copy all data from a file to a handle.
copyFileToHandle :: FilePath -> Handle -> IO ()

-- | Copy data from one handle to another until end of file.
copyHandleData :: Handle -> Handle -> IO ()

-- | Special directories for storing user-specific application data,
--   configuration, and cache files, as specified by the <a>XDG Base
--   Directory Specification</a>.
--   
--   Note: On Windows, <a>XdgData</a> and <a>XdgConfig</a> map to the same
--   directory.
data XdgDirectory

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

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

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

-- | Search paths for various application data, as specified by the <a>XDG
--   Base Directory Specification</a>.
--   
--   Note: On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> yield
--   the same result.
data XdgDirectoryList

-- | For data files (e.g. images). Defaults to
--   <tt><i>usr</i>local<i>share</i></tt> and <tt><i>usr</i>share/</tt> and
--   can be overridden by the <tt>XDG_DATA_DIRS</tt> environment variable.
--   On Windows, it is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt>
--   (e.g. <tt>C:/ProgramData</tt>).
XdgDataDirs :: XdgDirectoryList

-- | For configuration files. Defaults to <tt><i>etc</i>xdg</tt> and can be
--   overridden by the <tt>XDG_CONFIG_DIRS</tt> environment variable. On
--   Windows, it is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt>
--   (e.g. <tt>C:/ProgramData</tt>).
XdgConfigDirs :: XdgDirectoryList
createDirectoryInternal :: FilePath -> IO ()
removePathInternal :: Bool -> FilePath -> IO ()
renamePathInternal :: FilePath -> FilePath -> IO ()
c_free :: Ptr a -> IO ()
c_PATH_MAX :: Maybe Int
c_realpath :: CString -> CString -> IO CString
withRealpath :: CString -> (CString -> IO a) -> IO a
canonicalizePathWith :: ((FilePath -> IO FilePath) -> FilePath -> IO FilePath) -> FilePath -> IO FilePath
canonicalizePathSimplify :: FilePath -> IO FilePath
findExecutablesLazyInternal :: ([FilePath] -> String -> ListT IO FilePath) -> String -> ListT IO FilePath
exeExtensionInternal :: String
getDirectoryContentsInternal :: FilePath -> IO [FilePath]
getCurrentDirectoryInternal :: IO FilePath
prependCurrentDirectory :: FilePath -> IO FilePath
setCurrentDirectoryInternal :: FilePath -> IO ()
linkToDirectoryIsDirectory :: Bool
createSymbolicLink :: Bool -> FilePath -> FilePath -> IO ()
readSymbolicLink :: FilePath -> IO FilePath
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 ()
copyOwnerFromStatus :: FileStatus -> FilePath -> IO ()
copyGroupFromStatus :: FileStatus -> FilePath -> IO ()
tryCopyOwnerAndGroupFromStatus :: FileStatus -> FilePath -> IO ()
copyFileWithMetadataInternal :: (Metadata -> FilePath -> IO ()) -> (Metadata -> FilePath -> IO ()) -> FilePath -> FilePath -> IO ()
setTimes :: FilePath -> (Maybe POSIXTime, Maybe POSIXTime) -> IO ()

-- | Get the contents of the <tt>PATH</tt> environment variable.
getPath :: IO [FilePath]
getHomeDirectoryInternal :: IO FilePath
getXdgDirectoryInternal :: IO FilePath -> XdgDirectory -> IO FilePath
getXdgDirectoryListInternal :: XdgDirectoryList -> IO [FilePath]
getAppUserDataDirectoryInternal :: FilePath -> IO FilePath
getUserDocumentsDirectoryInternal :: IO FilePath
getTemporaryDirectoryInternal :: IO FilePath


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

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

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

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

-- | <tt><a>removeDirectoryRecursive</a> dir</tt> removes an existing
--   directory <i>dir</i> together with its contents and subdirectories.
--   Within this directory, symbolic links are removed without affecting
--   their targets.
--   
--   On Windows, the operation fails if <i>dir</i> is a directory symbolic
--   link.
removeDirectoryRecursive :: FilePath -> IO ()

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

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

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

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

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

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

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

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

-- | Special directories for storing user-specific application data,
--   configuration, and cache files, as specified by the <a>XDG Base
--   Directory Specification</a>.
--   
--   Note: On Windows, <a>XdgData</a> and <a>XdgConfig</a> map to the same
--   directory.
data XdgDirectory

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

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

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

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

-- | Search paths for various application data, as specified by the <a>XDG
--   Base Directory Specification</a>.
--   
--   Note: On Windows, <a>XdgDataDirs</a> and <a>XdgConfigDirs</a> yield
--   the same result.
data XdgDirectoryList

-- | For data files (e.g. images). Defaults to
--   <tt><i>usr</i>local<i>share</i></tt> and <tt><i>usr</i>share/</tt> and
--   can be overridden by the <tt>XDG_DATA_DIRS</tt> environment variable.
--   On Windows, it is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt>
--   (e.g. <tt>C:/ProgramData</tt>).
XdgDataDirs :: XdgDirectoryList

-- | For configuration files. Defaults to <tt><i>etc</i>xdg</tt> and can be
--   overridden by the <tt>XDG_CONFIG_DIRS</tt> environment variable. On
--   Windows, it is <tt>%PROGRAMDATA%</tt> or <tt>%ALLUSERSPROFILE%</tt>
--   (e.g. <tt>C:/ProgramData</tt>).
XdgConfigDirs :: XdgDirectoryList
getXdgDirectoryList :: XdgDirectoryList -> IO [FilePath]

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

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

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

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

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

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

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

-- | Copy a file with its associated metadata. If the destination file
--   already exists, it is overwritten. There is no guarantee of atomicity
--   in the replacement of the destination file. Neither path may refer to
--   an existing directory. If the source and/or destination are symbolic
--   links, the copy is performed on the targets of the links.
--   
--   On Windows, it behaves like the Win32 function <a>CopyFile</a>, which
--   copies various kinds of metadata including file attributes and
--   security resource properties.
--   
--   On Unix-like systems, permissions, access time, and modification time
--   are preserved. If possible, the owner and group are also preserved.
--   Note that the very act of copying can change the access time of the
--   source file, hence the access times of the two files may differ after
--   the 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
--   indirections from it as possible. Any trailing path separators are
--   discarded via <a>dropTrailingPathSeparator</a>. Additionally, on
--   Windows the letter case of the path is canonicalized.
--   
--   <b>Note</b>: This function is a very big hammer. If you only need an
--   absolute path, <a>makeAbsolute</a> is sufficient for removing
--   dependence on the current working directory.
--   
--   Indirections include the two special directories <tt>.</tt> and
--   <tt>..</tt>, as well as any symbolic links (and junction points on
--   Windows). The input path need not point to an existing file or
--   directory. Canonicalization is performed on the longest prefix of the
--   path that points to an existing file or directory. The remaining
--   portion of the path that does not point to an existing file or
--   directory will still undergo <a>normalise</a>, but case
--   canonicalization and indirection removal are skipped as they are
--   impossible to do on a nonexistent path.
--   
--   Most programs should not worry about the canonicity of a path. In
--   particular, despite the name, the function does not truly guarantee
--   canonicity of the returned path due to the presence of hard links,
--   mount points, etc.
--   
--   If the path points to an existing file or directory, then the output
--   path shall also point to the same file or directory, subject to the
--   condition that the relevant parts of the file system do not change
--   while the function is still running. In other words, the function is
--   definitively not atomic. The results can be utterly wrong if the
--   portions of the path change while this function is running.
--   
--   Since some indirections (symbolic links on all systems, <tt>..</tt> on
--   non-Windows systems, and junction points on Windows) are dependent on
--   the state of the existing filesystem, the function can only make a
--   conservative attempt by removing such indirections from the longest
--   prefix of the path that still points to an existing file or directory.
--   
--   Note that on Windows parent directories <tt>..</tt> are always fully
--   expanded before the symbolic links, as consistent with the rest of the
--   Windows API (such as <tt>GetFullPathName</tt>). In contrast, on POSIX
--   systems parent directories <tt>..</tt> are expanded alongside symbolic
--   links from left to right. To put this more concretely: if <tt>L</tt>
--   is a symbolic link for <tt>R/P</tt>, then on Windows <tt>L\..</tt>
--   refers to <tt>.</tt>, whereas on other operating systems <tt>L/..</tt>
--   refers to <tt>R</tt>.
--   
--   Similar to <a>normalise</a>, passing an empty path is equivalent to
--   passing the current directory.
--   
--   <tt>canonicalizePath</tt> can resolve at least 64 indirections in a
--   single path, more than what is supported by most operating systems.
--   Therefore, it may return the fully resolved path even though the
--   operating system itself would have long given up.
--   
--   On Windows XP or earlier systems, junction expansion is not performed
--   due to their lack of <tt>GetFinalPathNameByHandle</tt>.
--   
--   <i>Changes since 1.2.3.0:</i> The function has been altered to be more
--   robust and has the same exception behavior as <a>makeAbsolute</a>.
--   
--   <i>Changes since 1.3.0.0:</i> The function no longer preserves the
--   trailing path separator. File symbolic links that appear in the middle
--   of a path are properly dereferenced. Case canonicalization and
--   symbolic link expansion are now performed on Windows.
canonicalizePath :: FilePath -> IO FilePath

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

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

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

-- | The operation <a>doesFileExist</a> returns <a>True</a> if the argument
--   file 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
--   argument file exists and is either a directory or a symbolic link to a
--   directory, and <a>False</a> otherwise.
doesDirectoryExist :: FilePath -> IO Bool

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

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

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

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

-- | Search through the given list of directories for the given file and
--   returns all paths where the given file exists.
--   
--   The behavior is equivalent to <a>findFilesWith</a>. Details can be
--   found 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
--   given name and satisfies the given predicate and return the path of
--   the first occurrence. The directories are checked in a left-to-right
--   order.
--   
--   This is essentially a more performant version of <a>findFilesWith</a>
--   that always returns the first result, if any. Details can be found in
--   the documentation of <a>findFilesWith</a>.
findFileWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO (Maybe FilePath)

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

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

-- | Create a <i>file</i> symbolic link. The target path can be either
--   absolute or relative and need not refer to an existing file. The order
--   of arguments follows the POSIX convention.
--   
--   To remove an existing file symbolic link, use <a>removeFile</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is included
--   if supported by the operating system. On POSIX, the function uses
--   <tt>symlink</tt> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if 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
--   absolute or relative and need not refer to an existing directory. The
--   order of arguments follows the POSIX convention.
--   
--   To remove an existing directory symbolic link, use
--   <a>removeDirectoryLink</a>.
--   
--   Although the distinction between <i>file</i> symbolic links and
--   <i>directory</i> symbolic links does not exist on POSIX systems, on
--   Windows this is an intrinsic property of every symbolic link and
--   cannot be changed without recreating the link. A file symbolic link
--   that actually points to a directory will fail to dereference and vice
--   versa. Moreover, creating symbolic links on Windows may require
--   privileges unavailable to users outside the Administrators group.
--   Portable programs that use symbolic links should take both into
--   consideration.
--   
--   On Windows, the function is implemented using
--   <tt>CreateSymbolicLink</tt> with
--   <tt>SYMBOLIC_LINK_FLAG_DIRECTORY</tt>. Since 1.3.3.0, the
--   <tt>SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE</tt> flag is also
--   included if supported by the operating system. On POSIX, this is an
--   alias for <a>createFileLink</a> and is therefore atomic.
--   
--   Windows-specific errors: This operation may fail with
--   <a>permissionErrorType</a> if the user lacks the privileges to create
--   symbolic links. It may also fail with <a>illegalOperationErrorType</a>
--   if the file system does not support symbolic links.
createDirectoryLink :: FilePath -> FilePath -> IO ()

-- | Remove an existing <i>directory</i> symbolic link.
--   
--   On Windows, this is an alias for <a>removeDirectory</a>. On POSIX
--   systems, this is an alias for <a>removeFile</a>.
--   
--   See also: <a>removeFile</a>, which can remove an existing <i>file</i>
--   symbolic link.
removeDirectoryLink :: FilePath -> IO ()

-- | Check whether the path refers to a symbolic link. An exception is
--   thrown if the path does not exist or is inaccessible.
--   
--   On Windows, this checks for <tt>FILE_ATTRIBUTE_REPARSE_POINT</tt>. In
--   addition to symbolic links, the function also returns true on junction
--   points. 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.
--   The returned path may not be absolute, may not exist, and may not even
--   be a valid path.
--   
--   On Windows systems, this calls <tt>DeviceIoControl</tt> with
--   <tt>FSCTL_GET_REPARSE_POINT</tt>. In addition to symbolic links, the
--   function also works on junction points. On POSIX systems, this calls
--   <tt>readlink</tt>.
--   
--   Windows-specific errors: This operation may fail with
--   <a>illegalOperationErrorType</a> if the file system does not support
--   symbolic 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.
--   
--   On Windows, the <a>writable</a> permission corresponds to the
--   "read-only" attribute. The <a>executable</a> permission is set if the
--   file extension is of an executable file type. The <a>readable</a>
--   permission is always set.
--   
--   On POSIX systems, this returns the result of <tt>access</tt>.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>isPermissionError</a> if the user is not permitted to access
--   the permissions, or</li>
--   <li><a>isDoesNotExistError</a> if the file or directory does not
--   exist.</li>
--   </ul>
getPermissions :: FilePath -> IO Permissions

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

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

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

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

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

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

-- | <i>Deprecated: Use <a>pathIsSymbolicLink</a> instead</i>
isSymbolicLink :: FilePath -> IO Bool
