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


-- | Platform-agnostic library for filesystem operations
gr
grThis library provides a basic set of operations for manipulating files
grand directories in a portable way.
@package directory
@version 1.3.1.5


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

-- | Uninhabited data type
data Void

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

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

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

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

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

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

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

-- | This is the simplest of the exception-catching functions. It takes a
grsingle argument, runs it, and if an exception is raised the "handler"
gris executed, with the value of the exception passed as an argument.
grOtherwise, the result is returned as normal. For example:
gr
gr<pre>
grcatch (readFile f)
gr      (\e -&gt; do let err = show (e :: IOException)
gr                hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
gr                return "")
gr</pre>
gr
grNote that we have to give a type signature to <tt>e</tt>, or the
grprogram will not typecheck as the type is ambiguous. While it is
grpossible to catch exceptions of any type, see the section "Catching
grall exceptions" (in <a>Control.Exception</a>) for an explanation of
grthe problems with doing so.
gr
grFor catching exceptions in pure (non-<a>IO</a>) expressions, see the
grfunction <a>evaluate</a>.
gr
grNote that due to Haskell's unspecified evaluation order, an expression
grmay throw one of several possible exceptions: consider the expression
gr<tt>(error "urk") + (1 `div` 0)</tt>. Does the expression throw
gr<tt>ErrorCall "urk"</tt>, or <tt>DivideByZero</tt>?
gr
grThe answer is "it might throw either"; the choice is
grnon-deterministic. If you are catching any type of exception then you
grmight catch either. If you are calling <tt>catch</tt> with type <tt>IO
grInt -&gt; (ArithException -&gt; IO Int) -&gt; IO Int</tt> then the
grhandler may get run with <tt>DivideByZero</tt> as an argument, or an
gr<tt>ErrorCall "urk"</tt> exception may be propogated further up. If
gryou call it again, you might get a the opposite behaviour. This is ok,
grbecause <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
grhierarchy. When an exception of type <tt>e</tt> is thrown, behind the
grscenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException

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

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

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

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

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

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

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

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

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

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

-- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and
grreturns a list of all the <a>Just</a> values.
gr
gr<h4><b>Examples</b></h4>
gr
grBasic usage:
gr
gr<pre>
gr&gt;&gt;&gt; catMaybes [Just 1, Nothing, Just 3]
gr[1,3]
gr</pre>
gr
grWhen constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
grbe used to return all of the "success" results (if the list is the
grresult of a <a>map</a>, then <a>mapMaybe</a> would be more
grappropriate):
gr
gr<pre>
gr&gt;&gt;&gt; import Text.Read ( readMaybe )
gr
gr&gt;&gt;&gt; [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
gr[Just 1,Nothing,Just 3]
gr
gr&gt;&gt;&gt; catMaybes $ [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
gr[1,3]
gr</pre>
catMaybes :: () => [Maybe a] -> [a]

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

-- | The <a>fromMaybe</a> function takes a default value and and
gr<a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
grthe default values; otherwise, it returns the value contained in the
gr<a>Maybe</a>.
gr
gr<h4><b>Examples</b></h4>
gr
grBasic usage:
gr
gr<pre>
gr&gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
gr"Hello, World!"
gr</pre>
gr
gr<pre>
gr&gt;&gt;&gt; fromMaybe "" Nothing
gr""
gr</pre>
gr
grRead an integer from a string using <tt>readMaybe</tt>. If we fail to
grparse an integer, we want to return <tt>0</tt> by default:
gr
gr<pre>
gr&gt;&gt;&gt; import Text.Read ( readMaybe )
gr
gr&gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
gr5
gr
gr&gt;&gt;&gt; fromMaybe 0 (readMaybe "")
gr0
gr</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.
gr
grFor most types, the default definition for <a>mconcat</a> will be
grused, but the function is included in the class definition so that an
groptimized 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
grversion 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
grobject, or an array of objects, which may be marshalled to or from
grHaskell values of type <tt>a</tt>.
gr
grThe type <tt>a</tt> will often be an instance of class <a>Storable</a>
grwhich provides the marshalling operations. However this is not
gressential, and you can provide your own operations to access the
grpointer. For example you might write small foreign functions to get or
grset the fields of a C <tt>struct</tt>.
data Ptr a

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

-- | Windows only
DirectoryLink :: FileType

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

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

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


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

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

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

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

-- | <tt><a>removeDirectoryRecursive</a> dir</tt> removes an existing
grdirectory <i>dir</i> together with its contents and subdirectories.
grWithin this directory, symbolic links are removed without affecting
grtheir targets.
gr
grOn Windows, the operation fails if <i>dir</i> is a directory symbolic
grlink.
removeDirectoryRecursive :: FilePath -> IO ()

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

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

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

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

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

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

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

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

-- | Special directories for storing user-specific application data,
grconfiguration, and cache files, as specified by the <a>XDG Base
grDirectory Specification</a>.
gr
grNote: On Windows, <a>XdgData</a> and <a>XdgConfig</a> map to the same
grdirectory.
data XdgDirectory

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

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

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

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

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

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

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

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

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

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

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

-- | Copy a file with its associated metadata. If the destination file
gralready exists, it is overwritten. There is no guarantee of atomicity
grin the replacement of the destination file. Neither path may refer to
gran existing directory. If the source and/or destination are symbolic
grlinks, the copy is performed on the targets of the links.
gr
grOn Windows, it behaves like the Win32 function <a>CopyFile</a>, which
grcopies various kinds of metadata including file attributes and
grsecurity resource properties.
gr
grOn Unix-like systems, permissions, access time, and modification time
grare preserved. If possible, the owner and group are also preserved.
grNote that the very act of copying can change the access time of the
grsource file, hence the access times of the two files may differ after
grthe 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
grindirections from it as possible. Any trailing path separators are
grdiscarded via <a>dropTrailingPathSeparator</a>. Additionally, on
grWindows the letter case of the path is canonicalized.
gr
gr<b>Note</b>: This function is a very big hammer. If you only need an
grabsolute path, <a>makeAbsolute</a> is sufficient for removing
grdependence on the current working directory.
gr
grIndirections include the two special directories <tt>.</tt> and
gr<tt>..</tt>, as well as any symbolic links (and junction points on
grWindows). The input path need not point to an existing file or
grdirectory. Canonicalization is performed on the longest prefix of the
grpath that points to an existing file or directory. The remaining
grportion of the path that does not point to an existing file or
grdirectory will still undergo <a>normalise</a>, but case
grcanonicalization and indirection removal are skipped as they are
grimpossible to do on a nonexistent path.
gr
grMost programs should not worry about the canonicity of a path. In
grparticular, despite the name, the function does not truly guarantee
grcanonicity of the returned path due to the presence of hard links,
grmount points, etc.
gr
grIf the path points to an existing file or directory, then the output
grpath shall also point to the same file or directory, subject to the
grcondition that the relevant parts of the file system do not change
grwhile the function is still running. In other words, the function is
grdefinitively not atomic. The results can be utterly wrong if the
grportions of the path change while this function is running.
gr
grSince some indirections (symbolic links on all systems, <tt>..</tt> on
grnon-Windows systems, and junction points on Windows) are dependent on
grthe state of the existing filesystem, the function can only make a
grconservative attempt by removing such indirections from the longest
grprefix of the path that still points to an existing file or directory.
gr
grNote that on Windows parent directories <tt>..</tt> are always fully
grexpanded before the symbolic links, as consistent with the rest of the
grWindows API (such as <tt>GetFullPathName</tt>). In contrast, on POSIX
grsystems parent directories <tt>..</tt> are expanded alongside symbolic
grlinks from left to right. To put this more concretely: if <tt>L</tt>
gris a symbolic link for <tt>R/P</tt>, then on Windows <tt>L\..</tt>
grrefers to <tt>.</tt>, whereas on other operating systems <tt>L/..</tt>
grrefers to <tt>R</tt>.
gr
grSimilar to <a>normalise</a>, passing an empty path is equivalent to
grpassing the current directory.
gr
gr<tt>canonicalizePath</tt> can resolve at least 64 indirections in a
grsingle path, more than what is supported by most operating systems.
grTherefore, it may return the fully resolved path even though the
groperating system itself would have long given up.
gr
grOn Windows XP or earlier systems, junction expansion is not performed
grdue to their lack of <tt>GetFinalPathNameByHandle</tt>.
gr
gr<i>Changes since 1.2.3.0:</i> The function has been altered to be more
grrobust and has the same exception behavior as <a>makeAbsolute</a>.
gr
gr<i>Changes since 1.3.0.0:</i> The function no longer preserves the
grtrailing path separator. File symbolic links that appear in the middle
grof a path are properly dereferenced. Case canonicalization and
grsymbolic link expansion are now performed on Windows.
canonicalizePath :: FilePath -> IO FilePath

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

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

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

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

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

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

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

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

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

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

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

-- | Create a <i>file</i> symbolic link. The target path can be either
grabsolute or relative and need not refer to an existing file. The order
grof arguments follows the POSIX convention.
gr
grTo remove an existing file symbolic link, use <a>removeFile</a>.
gr
grAlthough the distinction between <i>file</i> symbolic links and
gr<i>directory</i> symbolic links does not exist on POSIX systems, on
grWindows this is an intrinsic property of every symbolic link and
grcannot be changed without recreating the link. A file symbolic link
grthat actually points to a directory will fail to dereference and vice
grversa. Moreover, creating symbolic links on Windows requires
grprivileges normally unavailable to users outside the Administrators
grgroup. Portable programs that use symbolic links should take both into
grconsideration.
gr
grOn Windows, the function is implemented using
gr<tt>CreateSymbolicLink</tt> with <tt>dwFlags</tt> set to zero. On
grPOSIX, the function uses <tt>symlink</tt> and is therefore atomic.
gr
grWindows-specific errors: This operation may fail with
gr<a>permissionErrorType</a> if the user lacks the privileges to create
grsymbolic links. It may also fail with <a>illegalOperationErrorType</a>
grif 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
grabsolute or relative and need not refer to an existing directory. The
grorder of arguments follows the POSIX convention.
gr
grTo remove an existing directory symbolic link, use
gr<a>removeDirectoryLink</a>.
gr
grAlthough the distinction between <i>file</i> symbolic links and
gr<i>directory</i> symbolic links does not exist on POSIX systems, on
grWindows this is an intrinsic property of every symbolic link and
grcannot be changed without recreating the link. A file symbolic link
grthat actually points to a directory will fail to dereference and vice
grversa. Moreover, creating symbolic links on Windows requires
grprivileges normally unavailable to users outside the Administrators
grgroup. Portable programs that use symbolic links should take both into
grconsideration.
gr
grOn Windows, the function is implemented using
gr<tt>CreateSymbolicLink</tt> with <tt>dwFlags</tt> set to
gr<tt>SYMBOLIC_LINK_FLAG_DIRECTORY</tt>. On POSIX, this is an alias for
gr<a>createFileLink</a> and is therefore atomic.
gr
grWindows-specific errors: This operation may fail with
gr<a>permissionErrorType</a> if the user lacks the privileges to create
grsymbolic links. It may also fail with <a>illegalOperationErrorType</a>
grif the file system does not support symbolic links.
createDirectoryLink :: FilePath -> FilePath -> IO ()

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

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

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

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

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

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

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

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

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