-- 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
