Libraries documentation moved to hslibs tree.
<ListItem>
<Para>
-Added simple high-level interface to the Regex library, see <XRef LinkEnd="RegexString">.
+Added simple high-level interface to the Regex library, see the libraries manual.
</Para>
</ListItem>
+++ /dev/null
-<Sect2 id="sec-byte-array">
-<Title>The ByteArray
-<IndexTerm><Primary>ByteArray</Primary></IndexTerm>
-interface
-</Title>
-
-<Para>
-<IndexTerm><Primary>ByteArray interface (GHC extensions)</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Literal>ByteArray</Literal>s are chunks of immutable Haskell heap:
-</Para>
-
-<Para>
-
-<ProgramListing>
-data ByteArray ix -- abstract
- -- instance of: Eq, CCallable.
-
-newByteArray :: Ix ix => (ix,ix) -> ST s (ByteArray ix)
-
-indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
-indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
-indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
-indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
-indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
-
-sizeofByteArray :: Ix ix => ByteArray ix -> Int
-</ProgramListing>
-
-<IndexTerm><Primary>newByteArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexCharArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexIntArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexAddrArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexFloatArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>sizeofByteArray</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Emphasis>Remarks:</Emphasis>
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-The operation <Function>newByteArray</Function> creates a byte array of length
-equal to the range of its indices <Emphasis>in bytes</Emphasis>.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Function>sizeofByteArray</Function> returns the size of the byte array, <Emphasis>in bytes</Emphasis>.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-Equality on byte arrays is value equality, not pointer equality (as is
-the case for its mutable variant.) Two byte arrays are equal if
-they're of the same length and they're pairwise equal.
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect2>
+++ /dev/null
-<Sect2 id="MutableArray">
-<Title>MutableArray
-<IndexTerm><Primary>MutableArray</Primary></IndexTerm>
-</Title>
-
-<Para>
-The <Literal>MutableArray</Literal> interface provide operations for reading and
-writing values to mutable arrays. There's two kinds of
-mutable arrays, the mutatable version of Haskell <Literal>Array</Literal>s
-and <Emphasis>mutable byte arrays</Emphasis>, chunks of memory containing
-values of some basic type.
-</Para>
-
-<Sect3 id="MutableArray-mutable-arrays">
-<Title>Mutable arrays
-<IndexTerm><Primary>Mutable arrays</Primary></IndexTerm>
-</Title>
-
-<Para>
-The mutable array section of the API provides the following
-operations:
-</Para>
-
-<Para>
-<ProgramListing>
-
--- mutable arrays:
-newArray :: Ix ix -> (ix,ix) -> elt -> ST s (MutableArray s ix elt)
-boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
-readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
-writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
-freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
-thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
-
-unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
-unsafeThawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
-</ProgramListing>
-
-<IndexTerm><Primary>newArray</Primary></IndexTerm>
-<IndexTerm><Primary>boundsOfArray</Primary></IndexTerm>
-<IndexTerm><Primary>readArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeArray</Primary></IndexTerm>
-<IndexTerm><Primary>freezeArray</Primary></IndexTerm>
-<IndexTerm><Primary>thawArray</Primary></IndexTerm>
-<IndexTerm><Primary>unsafeFreezeArray</Primary></IndexTerm>
-<IndexTerm><Primary>unsafeThawArray</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Emphasis>Remarks:</Emphasis>
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-The <Function>freezeArray</Function> action converts a mutable array into an
-immutable one by copying, whereas <Function>unsafeFreezeArray</Function> returns
-an immutable array that is effectively just the type cast version
-of the mutable array. Should you write to the mutable array after
-it has been (unsafely) frozen, you'll side-effect the immutable
-array in the process. Please don't :-)
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-The operation <Function>thawArray</Function> goes the other way, converting
-an immutable <Literal>Array</Literal> into a mutable one. This is done by
-copying. The operation <Function>unsafeThawArray</Function> is also provided,
-which places the same kind of proof obligation on the programmer
-as <Function>unsafeFreezeArray</Function> does.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect3>
-
-<Sect3 id="MutableArray-mutable-byte-arrays">
-<Title>Mutable byte arrays
-<IndexTerm><Primary>Mutable byte arrays</Primary></IndexTerm>
-</Title>
-
-<Para>
-<ProgramListing>
--- creators:
-newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newWordArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newStablePtrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-
-boundsOfMutableByteArray
- :: Ix ix => MutableByteArray s ix -> (ix, ix)
-
-readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
-readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
-readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
-readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
-readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
-readStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s (StablePtr a)
-readWord8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word8
-readWord16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word16
-readWord32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word32
-readWord64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word64
-readInt8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int8
-readInt16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int16
-readInt32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int32
-readInt64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int64
-
-writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
-writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
-writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
-writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
-writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
-writeStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> StablePtr a -> ST s ()
-writeWord8Array :: Ix ix => MutableByteArray s ix -> ix -> Word8 -> ST s ()
-writeWord16Array :: Ix ix => MutableByteArray s ix -> ix -> Word16 -> ST s ()
-writeWord32Array :: Ix ix => MutableByteArray s ix -> ix -> Word32 -> ST s ()
-writeWord64Array :: Ix ix => MutableByteArray s ix -> ix -> Word64 -> ST s ()
-writeInt8Array :: Ix ix => MutableByteArray s ix -> ix -> Int8 -> ST s ()
-writeInt16Array :: Ix ix => MutableByteArray s ix -> ix -> Int16 -> ST s ()
-writeInt32Array :: Ix ix => MutableByteArray s ix -> ix -> Int32 -> ST s ()
-writeInt64Array :: Ix ix => MutableByteArray s ix -> ix -> Int64 -> ST s ()
-
-freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeStablePtrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-
-unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-
-sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int
-
-thawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix)
-unsafeThawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix)
-</ProgramListing>
-
-<IndexTerm><Primary>newCharArray</Primary></IndexTerm>
-<IndexTerm><Primary>newAddrArray</Primary></IndexTerm>
-<IndexTerm><Primary>newIntArray</Primary></IndexTerm>
-<IndexTerm><Primary>newFloatArray</Primary></IndexTerm>
-<IndexTerm><Primary>newDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>boundsOfMutableByteArray</Primary></IndexTerm>
-<IndexTerm><Primary>readCharArray</Primary></IndexTerm>
-<IndexTerm><Primary>readIntArray</Primary></IndexTerm>
-<IndexTerm><Primary>readAddrArray</Primary></IndexTerm>
-<IndexTerm><Primary>readFloatArray</Primary></IndexTerm>
-<IndexTerm><Primary>readDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>readWord8Array</Primary></IndexTerm>
-<IndexTerm><Primary>readWord16Array</Primary></IndexTerm>
-<IndexTerm><Primary>readWord32Array</Primary></IndexTerm>
-<IndexTerm><Primary>readWord64Array</Primary></IndexTerm>
-<IndexTerm><Primary>readInt8Array</Primary></IndexTerm>
-<IndexTerm><Primary>readInt16Array</Primary></IndexTerm>
-<IndexTerm><Primary>readInt32Array</Primary></IndexTerm>
-<IndexTerm><Primary>readInt64Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeCharArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeIntArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeAddrArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeFloatArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>writeWord8Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeWord16Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeWord32Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeWord64Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeInt8Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeInt16Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeInt32Array</Primary></IndexTerm>
-<IndexTerm><Primary>writeInt64Array</Primary></IndexTerm>
-<IndexTerm><Primary>freezeCharArray</Primary></IndexTerm>
-<IndexTerm><Primary>freezeIntArray</Primary></IndexTerm>
-<IndexTerm><Primary>freezeAddrArray</Primary></IndexTerm>
-<IndexTerm><Primary>freezeFloatArray</Primary></IndexTerm>
-<IndexTerm><Primary>freezeDoubleArray</Primary></IndexTerm>
-<IndexTerm><Primary>unsafeFreezeByteArray</Primary></IndexTerm>
-<IndexTerm><Primary>unsafeThawByteArray</Primary></IndexTerm>
-<IndexTerm><Primary>thawByteArray</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Emphasis>Remarks:</Emphasis>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-A Mutable byte array is created by specifying its size in units of
-some basic type. For example,
-
-
-<ProgramListing>
-mkPair :: ST s (MutableByteArray s Int)
-mkPair = newIntArray (0,1)
-</ProgramListing>
-
-
-creates a mutable array capable of storing two <Literal>Int</Literal>s. Notice
-that the range size <Emphasis>is not in bytes</Emphasis>, but in units of the
-basic type.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-A mutable byte array is not parameterised over the kind of values
-it contains. A consequence of this is that it is possible to
-have byte arrays containing a mix of basic types, or even read
-a value from the array at a different type from which it was
-written, e.g.,
-
-<ProgramListing>
-isLitteEndian :: IO Bool
-isLitteEndian = stToIO $ do
- x <- newIntArray (0,1)
- writeIntArray x 1
- v <- readCharArray x 0
- return (v == chr 1)
-</ProgramListing>
-
-
-It's left as an exercise for the reader to determine whether having
-byte arrays not be parameterised over the type of values they
-contain is a bug or a feature..
-
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-As for mutable arrays, operations for turning mutable byte arrays
-into immutable byte arrays are also provided by the <Function>freeze*</Function>
-class of actions. There's also the non-copying
-<Function>unsafeFreezeByteArray</Function>.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-Operations for going the other way, where an immutable byte
-array is 'thawed' are also provided. <Function>thawByteArray</Function> does
-this by copying, whereas <Function>unsafeThawByteArray</Function> does not
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-The operation <Function>sizeofMutableByteArray</Function> returns the size of
-the array, <Emphasis>in bytes.</Emphasis>
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect3>
-
-</Sect2>
+++ /dev/null
-<Sect1 id="GHC-library">
-<Title>Miscellaneous libraries
-</Title>
-
-<Para>
-<IndexTerm><Primary>libraries, miscellaneous</Primary></IndexTerm>
-<IndexTerm><Primary>misc, syslib</Primary></IndexTerm>
-</Para>
-
-<Para>
-This section describes a collection of Haskell libraries we've
-collected over the years. Access to any of these modules is provided
-by giving the <Option>-syslib misc</Option><IndexTerm><Primary>-syslib misc option</Primary></IndexTerm>.
-</Para>
-
-<Sect2 id="Bag">
-<Title>The <Literal>Bag</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>Bag module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-A <Emphasis>bag</Emphasis> is an unordered collection of elements which may contain
-duplicates. To use, <Literal>import Bag</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data Bag elt -- abstract
-
-emptyBag :: Bag elt
-unitBag :: elt -> Bag elt
-
-consBag :: elt -> Bag elt -> Bag elt
-snocBag :: Bag elt -> elt -> Bag elt
-
-unionBags :: Bag elt -> Bag elt -> Bag elt
-unionManyBags :: [Bag elt] -> Bag elt
-
-isEmptyBag :: Bag elt -> Bool
-elemBag :: Eq elt => elt -> Bag elt -> Bool
-
-filterBag :: (elt -> Bool) -> Bag elt -> Bag elt
-partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt)
- -- returns the elements that do/don't satisfy the predicate
-
-concatBag :: Bag (Bag a) -> Bag a
-foldBag :: (r -> r -> r) -> (a -> r) -> r -> Bag a -> r
-mapBag :: (a -> b) -> Bag a -> Bag b
-
-listToBag :: [elt] -> Bag elt
-bagToList :: Bag elt -> [elt]
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="FiniteMap">
-<Title>The <Literal>FiniteMap</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>FiniteMap module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-What functional programmers call a <Emphasis>finite map</Emphasis>, everyone else
-calls a <Emphasis>lookup table</Emphasis>.
-</Para>
-
-<Para>
-Out code is derived from that in this paper:
-<QUOTE
->S Adams
-"Efficient sets: a balancing act"
-Journal of functional programming 3(4) Oct 1993, pages 553-562</QUOTE
->
-Guess what? The implementation uses balanced trees.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data FiniteMap key elt -- abstract
-
--- BUILDING
-emptyFM :: FiniteMap key elt
-unitFM :: key -> elt -> FiniteMap key elt
-listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt
- -- In the case of duplicates, the last is taken
-
--- ADDING AND DELETING
- -- Throws away any previous binding
- -- In the list case, the items are added starting with the
- -- first one in the list
-addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt
-addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt
-
- -- Combines with previous binding
- -- In the combining function, the first argument is
- -- the "old" element, while the second is the "new" one.
-addToFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> key -> elt
- -> FiniteMap key elt
-addListToFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> [(key,elt)]
- -> FiniteMap key elt
-
- -- Deletion doesn't complain if you try to delete something
- -- which isn't there
-delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt
-delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt
-
--- COMBINING
- -- Bindings in right argument shadow those in the left
-plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt
- -> FiniteMap key elt
-
- -- Combines bindings for the same thing with the given function
-plusFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-
-minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
- -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2
-
-intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-intersectFM_C :: Ord key => (elt -> elt -> elt)
- -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
-
--- MAPPING, FOLDING, FILTERING
-foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a
-mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2
-filterFM :: Ord key => (key -> elt -> Bool)
- -> FiniteMap key elt -> FiniteMap key elt
-
--- INTERROGATING
-sizeFM :: FiniteMap key elt -> Int
-isEmptyFM :: FiniteMap key elt -> Bool
-
-elemFM :: Ord key => key -> FiniteMap key elt -> Bool
-lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt
-lookupWithDefaultFM
- :: Ord key => FiniteMap key elt -> elt -> key -> elt
- -- lookupWithDefaultFM supplies a "default" elt
- -- to return for an unmapped key
-
--- LISTIFYING
-fmToList :: FiniteMap key elt -> [(key,elt)]
-keysFM :: FiniteMap key elt -> [key]
-eltsFM :: FiniteMap key elt -> [elt]
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="ListSetOps">
-<Title>The <Literal>ListSetOps</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>ListSetOps module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-Just a few set-sounding operations on lists. If you want sets, use
-the <Literal>Set</Literal> module.
-</Para>
-
-<Para>
-
-<ProgramListing>
-unionLists :: Eq a => [a] -> [a] -> [a]
-intersectLists :: Eq a => [a] -> [a] -> [a]
-minusList :: Eq a => [a] -> [a] -> [a]
-disjointLists :: Eq a => [a] -> [a] -> Bool
-intersectingLists :: Eq a => [a] -> [a] -> Bool
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="Maybes">
-<Title>The <Literal>Maybes</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>Maybes module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>Maybe</Literal> type is in the Haskell 1.4 prelude. Moreover, the
-required <Literal>Maybe</Literal> library provides many useful functions on
-<Literal>Maybe</Literal>s. This (pre-1.3) module provides some more:
-</Para>
-
-<Para>
-An <Literal>Either</Literal>-like type called <Literal>MaybeErr</Literal>:
-
-<ProgramListing>
-data MaybeErr val err = Succeeded val | Failed err
-</ProgramListing>
-
-</Para>
-
-<Para>
-Some operations to do with <Literal>Maybe</Literal> (some commentary follows):
-
-<ProgramListing>
-maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True
-allMaybes :: [Maybe a] -> Maybe [a]
-firstJust :: [Maybe a] -> Maybe a
-findJust :: (a -> Maybe b) -> [a] -> Maybe b
-
-assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b
-mkLookupFun :: (key -> key -> Bool) -- Equality predicate
- -> [(key,val)] -- The assoc list
- -> (key -> Maybe val) -- A lookup fun to use
-mkLookupFunDef :: (key -> key -> Bool) -- Equality predicate
- -> [(key,val)] -- The assoc list
- -> val -- Value to return on failure
- -> key -- The key
- -> val -- The corresponding value
-
- -- a monad thing
-thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
-returnMaybe :: a -> Maybe a
-failMaybe :: Maybe a
-mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b]
-</ProgramListing>
-
-</Para>
-
-<Para>
-NB: <Function>catMaybes</Function> which used to be here, is now available via the
-standard <Literal>Maybe</Literal> interface (<Literal>Maybe</Literal> is an instance of <Literal>MonadPlus</Literal>).
-</Para>
-
-<Para>
-<Function>allMaybes</Function> collects a list of <Literal>Justs</Literal> into a single <Literal>Just</Literal>, returning
-<Literal>Nothing</Literal> if there are any <Literal>Nothings</Literal>.
-</Para>
-
-<Para>
-<Function>firstJust</Function> takes a list of <Literal>Maybes</Literal> and returns the
-first <Literal>Just</Literal> if there is one, or <Literal>Nothing</Literal> otherwise.
-</Para>
-
-<Para>
-<Function>assocMaybe</Function> looks up in an association list, returning
-<Literal>Nothing</Literal> if it fails.
-</Para>
-
-<Para>
-Now, some operations to do with <Literal>MaybeErr</Literal> (comments follow):
-
-<ProgramListing>
- -- a monad thing (surprise, surprise)
-thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err
-returnMaB :: val -> MaybeErr val err
-failMaB :: err -> MaybeErr val err
-
-listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
-foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
- -> acc
- -> [input]
- -> MaybeErr acc [err]
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>listMaybeErrs</Function> takes a list of <Literal>MaybeErrs</Literal> and, if they all succeed,
-returns a <Literal>Succeeded</Literal> of a list of their values. If any fail, it
-returns a <Literal>Failed</Literal> of the list of all the errors in the list.
-</Para>
-
-<Para>
-<Function>foldlMaybeErrs</Function> works along a list, carrying an accumulator; it
-applies the given function to the accumulator and the next list item,
-accumulating any errors that occur.
-</Para>
-
-</Sect2>
-
-<Sect2 id="memo-library">
-<Title>The <Literal>Memo</Literal> library
-</Title>
-
-<Para>
-<IndexTerm><Primary>Memo (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>Memo</Literal> library provides fast polymorphic memo functions using hash
-tables. The interface is:
-</Para>
-
-<Para>
-
-<ProgramListing>
-memo :: (a -> b) -> a -> b
-</ProgramListing>
-
-</Para>
-
-<Para>
-So, for example, <Function>memo f</Function> is a version of <Function>f</Function> that caches the results
-of previous calls.
-</Para>
-
-<Para>
-The searching is very fast, being based on pointer equality. One
-consequence of this is that the caching will only be effective if
-<Emphasis>exactly the same argument is passed again to the memoised
-function</Emphasis>. This means not just a copy of a previous argument, but the
-same instance. It's not useful to memoise integer functions using
-this interface, because integers are generally copied a lot and two
-instances of '27' are unlikely to refer to the same object.
-</Para>
-
-<Para>
-This memoisation library works well when the keys are large (or even
-infinite).
-</Para>
-
-<Para>
-The memo table implementation uses weak pointers and stable names (see
-the GHC/Hugs library document) to avoid space leaks and allow hashing
-for arbitrary Haskell objects. NOTE: while individual memo table
-entries will be garbage collected if the associated key becomes
-garbage, the memo table itself will not be collected if the function
-becomes garbage. We plan to fix this in a future version.
-</Para>
-
-<Para>
-There's another version of <Function>memo</Function> if you want to explicitly give a
-size for the hash table (the default size is 1001 buckets):
-</Para>
-
-<Para>
-
-<ProgramListing>
-memo_sized :: Int -> (a -> b) -> a -> b
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="PackedString">
-<Title>The <Literal>PackedString</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>PackedString module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-You need to <Literal>import PackedString</Literal> and heave in your
-<Option>-syslib ghc</Option> to use <Literal>PackedString</Literal>s.
-</Para>
-
-<Para>
-The basic type and functions available are:
-
-<ProgramListing>
-data PackedString -- abstract
-
-packString :: [Char] -> PackedString
-packStringST :: [Char] -> ST s PackedString
-packCBytesST :: Int -> Addr -> ST s PackedString
-packBytesForCST :: [Char] -> ST s (ByteArray Int)
-byteArrayToPS :: ByteArray Int -> PackedString
-unsafeByteArrayToPS :: ByteArray a -> Int -> PackedString
-psToByteArray :: PackedString -> ByteArray Int
-psToByteArrayST :: PackedString -> ST s (ByteArray Int)
-
-unpackPS :: PackedString -> [Char]
-</ProgramListing>
-
-</Para>
-
-<Para>
-We also provide a wad of list-manipulation-like functions:
-
-<ProgramListing>
-nilPS :: PackedString
-consPS :: Char -> PackedString -> PackedString
-
-headPS :: PackedString -> Char
-tailPS :: PackedString -> PackedString
-nullPS :: PackedString -> Bool
-appendPS :: PackedString -> PackedString -> PackedString
-lengthPS :: PackedString -> Int
-indexPS :: PackedString -> Int -> Char
- -- 0-origin indexing into the string
-mapPS :: (Char -> Char) -> PackedString -> PackedString
-filterPS :: (Char -> Bool) -> PackedString -> PackedString
-foldlPS :: (a -> Char -> a) -> a -> PackedString -> a
-foldrPS :: (Char -> a -> a) -> a -> PackedString -> a
-takePS :: Int -> PackedString -> PackedString
-dropPS :: Int -> PackedString -> PackedString
-splitAtPS :: Int -> PackedString -> (PackedString, PackedString)
-takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
-dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
-spanPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
-breakPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
-linesPS :: PackedString -> [PackedString]
-wordsPS :: PackedString -> [PackedString]
-reversePS :: PackedString -> PackedString
-concatPS :: [PackedString] -> PackedString
-elemPS :: Char -> PackedString -> Bool
- -- Perl-style split&join
-splitPS :: Char -> PackedString -> [PackedString]
-splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
-joinPS :: PackedString -> [PackedString] -> PackedString
-
-substrPS :: PackedString -> Int -> Int -> PackedString
- -- pluck out a piece of a PackedString
- -- start and end chars you want; both 0-origin-specified
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="Set">
-<Title>The <Literal>Set</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>Set module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-Our implementation of <Emphasis>sets</Emphasis> (key property: no duplicates) is just
-a variant of the <Literal>FiniteMap</Literal> module.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data Set -- abstract
- -- instance of: Eq
-
-emptySet :: Set a
-mkSet :: Ord a => [a] -> Set a
-setToList :: Set a -> [a]
-unitSet :: a -> Set a
-singletonSet :: a -> Set a -- deprecated, use unitSet.
-
-union :: Ord a => Set a -> Set a -> Set a
-unionManySets :: Ord a => [Set a] -> Set a
-minusSet :: Ord a => Set a -> Set a -> Set a
-mapSet :: Ord a => (b -> a) -> Set b -> Set a
-intersect :: Ord a => Set a -> Set a -> Set a
-
-elementOf :: Ord a => a -> Set a -> Bool
-isEmptySet :: Set a -> Bool
-
-cardinality :: Set a -> Int
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="BitSet">
-<Title>The <Literal>BitSet</Literal> interface
-</Title>
-
-<Para>
-<IndexTerm><Primary>Bitset interface (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-Bit sets are a fast implementation of sets of integers ranging from 0
-to one less than the number of bits in a machine word (typically 31).
-If any element exceeds the maximum value for a particular machine
-architecture, the results of these operations are undefined. You have
-been warned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data BitSet -- abstract
- -- instance of:
-
-emptyBS :: BitSet
-mkBS :: [Int] -> BitSet
-unitBS :: Int -> BitSet
-unionBS :: BitSet -> BitSet -> BitSet
-minusBS :: BitSet -> BitSet -> BitSet
-isEmptyBS :: BitSet -> Bool
-intersectBS :: BitSet -> BitSet -> BitSet
-elementBS :: Int -> BitSet -> Bool
-listBS :: BitSet -> [Int]
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="Util">
-<Title>The <Literal>Util</Literal> type
-</Title>
-
-<Para>
-<IndexTerm><Primary>Util module (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-Stuff that has been generally useful to use in writing the compiler.
-Don't be too surprised if this stuff moves/gets-renamed/etc.
-</Para>
-
-<Para>
-
-<ProgramListing>
--- general list processing
-forall :: (a -> Bool) -> [a] -> Bool
-exists :: (a -> Bool) -> [a] -> Bool
-
-nOfThem :: Int -> a -> [a]
-lengthExceeds :: [a] -> Int -> Bool
-isSingleton :: [a] -> Bool
-
---paranoid zip'ing (equal length lists)
-zipEqual :: [a] -> [b] -> [(a,b)]
-zipWithEqual :: String -> (a->b->c) -> [a]->[b]->[c]
-zipWith3Equal :: String -> (a->b->c->d) -> [a]->[b]->[c]->[d]
-zipWith4Equal :: String -> (a->b->c->d->e) -> [a]->[b]->[c]->[d]->[e]
--- lazy in second argument
-zipLazy :: [a] -> [b] -> [(a,b)]
-
-mapAndUnzip :: (a -> (b, c)) -> [a] -> ([b], [c])
-mapAndUnzip3 :: (a -> (b, c, d)) -> [a] -> ([b], [c], [d])
-
--- prefix and suffix matching on lists of characters.
-startsWith :: {-prefix-}String -> String -> Maybe String
-endsWith :: {-suffix-}String -> String -> Maybe String
-
--- association lists
-assoc :: Eq a => String -> [(a, b)] -> a -> b
-
--- duplicate handling
-hasNoDups :: Eq a => [a] -> Bool
-equivClasses :: (a -> a -> Ordering) -> [a] -> [[a]]
-runs :: (a -> a -> Bool) -> [a] -> [[a]]
-removeDups :: (a -> a -> Ordering) -> [a] -> ([a], [[a]])
-
--- sorting (don't complain of no choice...)
-quicksort :: (a -> a -> Bool) -> [a] -> [a]
-sortLt :: (a -> a -> Bool) -> [a] -> [a]
-stableSortLt :: (a -> a -> Bool) -> [a] -> [a]
-mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a]
-mergeSort :: Ord a => [a] -> [a]
-naturalMergeSort :: Ord a => [a] -> [a]
-mergeSortLe :: Ord a => [a] -> [a]
-naturalMergeSortLe :: Ord a => [a] -> [a]
-
--- transitive closures
-transitiveClosure :: (a -> [a]) -- Successor function
- -> (a -> a -> Bool) -- Equality predicate
- -> [a]
- -> [a] -- The transitive closure
-
--- accumulating (Left, Right, Bi-directional)
-mapAccumL :: (acc -> x -> (acc, y))
- -- Function of elt of input list and
- -- accumulator, returning new accumulator and
- -- elt of result list
- -> acc -- Initial accumulator
- -> [x] -- Input list
- -> (acc, [y]) -- Final accumulator and result list
-
-mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
-
-mapAccumB :: (accl -> accr -> x -> (accl, accr,y))
- -> accl -> accr -> [x]
- -> (accl, accr, [y])
-
---list comparison with explicit element comparer.
-cmpList :: (a -> a -> Ordering) -> [a] -> [a] -> Ordering
-
--- pairs
-applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d)
-applyToFst :: (a -> c) -> (a, b) -> (c, b)
-applyToSnd :: (b -> d) -> (a, b) -> (a, d)
-foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b)
-unzipWith :: (a -> b -> c) -> [(a, b)] -> [c]
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="C-interfaces">
-<Title>Interfaces to C libraries
-</Title>
-
-<Para>
-<IndexTerm><Primary>C library interfaces</Primary></IndexTerm>
-<IndexTerm><Primary>interfaces, C library</Primary></IndexTerm>
-</Para>
-
-<Para>
-The GHC system library (<Option>-syslib misc</Option>) also provides interfaces to
-several useful C libraries, mostly from the GNU project.
-</Para>
-
-<Sect2 id="Readline">
-<Title>The <Literal>Readline</Literal> interface
-</Title>
-
-<Para>
-<IndexTerm><Primary>Readline library (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>command-line editing library</Primary></IndexTerm>
-</Para>
-
-<Para>
-(Darren Moffat supplied the <Literal>Readline</Literal> interface.)
-</Para>
-
-<Para>
-The <Literal>Readline</Literal> module is a straightforward interface to the GNU
-Readline library. As such, you will need to look at the GNU
-documentation (and have a <Filename>libreadline.a</Filename> file around somewhere…)
-</Para>
-
-<Para>
-You'll need to link any Readlining program with <Option>-lreadline -ltermcap</Option>,
-besides the usual <Option>-syslib ghc</Option> (and <Option>-fhaskell-1.3</Option>).
-</Para>
-
-<Para>
-The main function you'll use is:
-
-<ProgramListing>
-readline :: String{-the prompt-} -> IO String
-</ProgramListing>
-
-</Para>
-
-<Para>
-If you want to mess around with Full Readline G(l)ory, we also
-provide:
-
-<ProgramListing>
-rlInitialize, addHistory,
-
-rlBindKey, rlAddDefun, RlCallbackFunction(..),
-
-rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd,
-rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput,
-
-rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName
-</ProgramListing>
-
-(All those names are just Haskellised versions of what you
-will see in the GNU readline documentation.)
-</Para>
-
-</Sect2>
-
-<Sect2 id="Regex">
-<Title>The <Literal>Regex</Literal> and <Literal>MatchPS</Literal> interfaces
-</Title>
-
-<Para>
-<IndexTerm><Primary>Regex library (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>MatchPS library (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>regular-expressions library</Primary></IndexTerm>
-</Para>
-
-<Para>
-(Sigbjorn Finne supplied the regular-expressions interface.)
-</Para>
-
-<Para>
-The <Literal>Regex</Literal> library provides quite direct interface to the GNU
-regular-expression library, for doing manipulation on <Literal>PackedString</Literal>s.
-You probably need to see the GNU documentation if you are operating at
-this level. Alternatively, you can use the simpler and higher-level
-<Literal>RegexString</Literal> interface.
-</Para>
-
-<Para>
-The datatypes and functions that <Literal>Regex</Literal> provides are:
-
-<ProgramListing>
-data PatBuffer # just a bunch of bytes (mutable)
-
-data REmatch
- = REmatch (Array Int GroupBounds) -- for $1, ... $n
- GroupBounds -- for $` (everything before match)
- GroupBounds -- for $& (entire matched string)
- GroupBounds -- for $' (everything after)
- GroupBounds -- for $+ (matched by last bracket)
-
--- GroupBounds hold the interval where a group
--- matched inside a string, e.g.
---
--- matching "reg(exp)" "a regexp" returns the pair (5,7) for the
--- (exp) group. (PackedString indices start from 0)
-
-type GroupBounds = (Int, Int)
-
-re_compile_pattern
- :: PackedString -- pattern to compile
- -> Bool -- True <=> assume single-line mode
- -> Bool -- True <=> case-insensitive
- -> PrimIO PatBuffer
-
-re_match :: PatBuffer -- compiled regexp
- -> PackedString -- string to match
- -> Int -- start position
- -> Bool -- True <=> record results in registers
- -> PrimIO (Maybe REmatch)
-
--- Matching on 2 strings is useful when you're dealing with multiple
--- buffers, which is something that could prove useful for
--- PackedStrings, as we don't want to stuff the contents of a file
--- into one massive heap chunk, but load (smaller chunks) on demand.
-
-re_match2 :: PatBuffer -- 2-string version
- -> PackedString
- -> PackedString
- -> Int
- -> Int
- -> Bool
- -> PrimIO (Maybe REmatch)
-
-re_search :: PatBuffer -- compiled regexp
- -> PackedString -- string to search
- -> Int -- start index
- -> Int -- stop index
- -> Bool -- True <=> record results in registers
- -> PrimIO (Maybe REmatch)
-
-re_search2 :: PatBuffer -- Double buffer search
- -> PackedString
- -> PackedString
- -> Int -- start index
- -> Int -- range (?)
- -> Int -- stop index
- -> Bool -- True <=> results in registers
- -> PrimIO (Maybe REmatch)
-</ProgramListing>
-
-</Para>
-
-<Para>
-The <Literal>MatchPS</Literal> module provides Perl-like ``higher-level'' facilities
-to operate on <Literal>PackedStrings</Literal>. The regular expressions in
-question are in Perl syntax. The ``flags'' on various functions can
-include: <Option>i</Option> for case-insensitive, <Option>s</Option> for single-line mode, and
-<Option>g</Option> for global. (It's probably worth your time to peruse the
-source code…)
-</Para>
-
-<Para>
-
-<ProgramListing>
-matchPS :: PackedString -- regexp
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch -- info about what matched and where
-
-searchPS :: PackedString -- regexp
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch
-
--- Perl-like match-and-substitute:
-substPS :: PackedString -- regexp
- -> PackedString -- replacement
- -> [Char] -- flags
- -> PackedString -- string
- -> PackedString
-
--- same as substPS, but no prefix and suffix:
-replacePS :: PackedString -- regexp
- -> PackedString -- replacement
- -> [Char] -- flags
- -> PackedString -- string
- -> PackedString
-
-match2PS :: PackedString -- regexp
- -> PackedString -- string1 to match
- -> PackedString -- string2 to match
- -> [Char] -- flags
- -> Maybe REmatch
-
-search2PS :: PackedString -- regexp
- -> PackedString -- string to match
- -> PackedString -- string to match
- -> [Char] -- flags
- -> Maybe REmatch
-
--- functions to pull the matched pieces out of an REmatch:
-
-getMatchesNo :: REmatch -> Int
-getMatchedGroup :: REmatch -> Int -> PackedString -> PackedString
-getWholeMatch :: REmatch -> PackedString -> PackedString
-getLastMatch :: REmatch -> PackedString -> PackedString
-getAfterMatch :: REmatch -> PackedString -> PackedString
-
--- (reverse) brute-force string matching;
--- Perl equivalent is index/rindex:
-findPS, rfindPS :: PackedString -> PackedString -> Maybe Int
-
--- Equivalent to Perl "chop" (off the last character, if any):
-chopPS :: PackedString -> PackedString
-
--- matchPrefixPS: tries to match as much as possible of strA starting
--- from the beginning of strB (handy when matching fancy literals in
--- parsers):
-matchPrefixPS :: PackedString -> PackedString -> Int
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="RegexString">
-<Title>The <Literal>RegexString</Literal> interface
-</Title>
-
-<Para>
-<IndexTerm><Primary>RegexString library (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>regular-expressions library</Primary></IndexTerm>
-</Para>
-
-<Para>
-(Simon Marlow supplied the String Regex wrapper.)
-</Para>
-
-<Para>
-For simple regular expression operations, the <Literal>Regex</Literal> library is a
-little heavyweight. <Literal>RegexString</Literal> permits regex matching on ordinary
-Haskell <Literal>String</Literal>s.
-</Para>
-
-<Para>
-The datatypes and functions that <Literal>RegexString</Literal> provides are:
-
-<ProgramListing>
-data Regex -- a compiled regular expression
-
-mkRegex
- :: String -- regexp to compile
- -> Regex -- compiled regexp
-
-matchRegex
- :: Regex -- compiled regexp
- -> String -- string to match
- -> Maybe [String] -- text of $1, $2, ... (if matched)
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="Socket">
-<Title>Network-interface toolkit—<Literal>Socket</Literal> and <Literal>SocketPrim</Literal>
-</Title>
-
-<Para>
-<IndexTerm><Primary>SocketPrim interface (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>Socket interface (misc syslib)</Primary></IndexTerm>
-<IndexTerm><Primary>network-interface library</Primary></IndexTerm>
-<IndexTerm><Primary>sockets library</Primary></IndexTerm>
-<IndexTerm><Primary>BSD sockets library</Primary></IndexTerm>
-(Darren Moffat supplied the initial version of this library.)
-</Para>
-
-<Para>
-Your best bet for documentation is to look at the code—really!—
-normally in
-<Filename>fptools/ghc/lib/misc/{BSD,Socket,SocketPrim</Filename>.lhs}.
-</Para>
-
-<Para>
-The <Literal>BSD</Literal> module provides functions to get at
-system-database info; pretty straightforward if you're into this sort of
-thing:
-
-<ProgramListing>
-getHostName :: IO String
-
-getServiceByName :: ServiceName -> IO ServiceEntry
-getServicePortNumber:: ServiceName -> IO PortNumber
-getServiceEntry :: IO ServiceEntry
-setServiceEntry :: Bool -> IO ()
-endServiceEntry :: IO ()
-
-getProtocolByName :: ProtocolName -> IO ProtocolEntry
-getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry
-getProtocolNumber :: ProtocolName -> ProtocolNumber
-getProtocolEntry :: IO ProtocolEntry
-setProtocolEntry :: Bool -> IO ()
-endProtocolEntry :: IO ()
-
-getHostByName :: HostName -> IO HostEntry
-getHostByAddr :: Family -> HostAddress -> IO HostEntry
-getHostEntry :: IO HostEntry
-setHostEntry :: Bool -> IO ()
-endHostEntry :: IO ()
-</ProgramListing>
-</Para>
-
-<Para>
-The <Literal>SocketPrim</Literal> interface provides quite direct access to
-the socket facilities in a BSD Unix system, including all the
-complications. We hope you don't need to use it! See the source if
-needed…
-</Para>
-
-<Para>
-The <Literal>Socket</Literal> interface is a ``higher-level'' interface to
-sockets, and it is what we recommend. Please tell us if the facilities it
-offers are inadequate to your task!
-</Para>
-
-<Para>
-The interface is relatively modest:
-
-<ProgramListing>
-connectTo :: Hostname -> PortID -> IO Handle
-listenOn :: PortID -> IO Socket
-
-accept :: Socket -> IO (Handle, HostName)
-sendTo :: Hostname -> PortID -> String -> IO ()
-
-recvFrom :: Hostname -> PortID -> IO String
-socketPort :: Socket -> IO PortID
-
-data PortID -- PortID is a non-abstract type
- = Service String -- Service Name eg "ftp"
- | PortNumber PortNumber -- User defined Port Number
- | UnixSocket String -- Unix family socket in file system
-
-type Hostname = String
-
- -- 16-bit value (stored in network byte order).
-data PortNumber
- -- instance of: Eq, Num, Show.
-
-mkPortNumber :: Int -> PortNumber
-</ProgramListing>
-</Para>
-
-<Para>
-Various examples of networking Haskell code are provided in
-</Para>
-
-</Sect2>
-
-<Sect2 id="Select">
-<Title>The <Literal>Select</Literal> interface
-</Title>
-
-<Para>
-<IndexTerm><Primary>Select interface (misc syslib)</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>Select</Literal> interface provides a Haskell wrapper for the <Function>select()</Function>
-OS call supplied by many modern UNIX variants. <Literal>Select</Literal> exports the
-following:
-</Para>
-
-<Para>
-
-<ProgramListing>
-type TimeOut = Maybe Int
- -- Nothing => wait indefinitely.
- -- Just x | x >= 0 => block waiting for 'x' micro seconds.
- -- | otherwise => block waiting for '-x' micro seconds.
-
-hSelect :: [Handle]
- -> [Handle]
- -> [Handle]
- -> TimeOut
- -> IO SelectResult
-
-type SelectResult
- = ( [Handle] -- input handles ready
- , [Handle] -- output handles ready
- , [Handle] -- exc. handles ready
- )
-</ProgramListing>
-
-</Para>
-
-<Para>
-Here's an example of how it could be used:
-</Para>
-
-<Para>
-
-<ProgramListing>
-module Main(main) where
-
-import Select
-import IO
-
-main :: IO ()
-main = do
- hSetBuffering stdin NoBuffering
- putStrLn "waiting for input to appear"
- hSelect [stdin] [] [] Nothing
- putStrLn "input ready, let's try reading"
- x <- getChar
- print x
-</ProgramListing>
-
-</Para>
-
-<Para>
-where the call to <Function>hSelect</Function> makes the process go to sleep
-until there's input available on <VarName>stdin</VarName>.
-</Para>
-
-<Para>
-Notice that this particular use of <Function>hSelect</Function> is now really a no-op
-with GHC compiled code, as its implementation of IO will take care to
-avoid blocking the process (i.e., all running Haskell threads), and
-call <Function>select()</Function> for you, if needs be. However, <Function>hSelect</Function> exposes
-functionality that is useful in other contexts (e.g., you want to
-wait for input on two <Literal>Handles</Literal> for 3 seconds, but no longer.)
-</Para>
-
-</Sect2>
-
-</Sect1>
</Sect1>
-<Sect1>
-<Title>GHC/Hugs Extension Libraries</Title>
-
-<Para>
-The extension libraries provided by both GHC and Hugs are described in
-the
-<ULink
-URL="libs.html">GHC/Hugs Extension Library Document</ULink>
-</Para>
-
-</Sect1>
<Sect1>
<Title>GHC-only Extension Libraries</Title>
</Para>
<Para>
-If you turn on <Option>-fglasgow-exts</Option>, a new world opesn up to you and the compiler
+If you turn on <Option>-fglasgow-exts</Option>, a new world opens up to you and the compiler
will recognise and parse unboxed values properly, and provide access to the
various interfaces libraries described here (and piles of other goodies.)
</Para>
-&mutablearray
-&bytearray
-
-<Sect2>
-<Title>The <Literal>CCall</Literal> module</Title>
-
-<Para>
-The <Literal>CCall</Literal> module defines the classes <Literal>CCallable</Literal> and <Literal>CReturnable</Literal>,
-along with instances for the primitive types (<Literal>Int</Literal>, <Literal>Int#</Literal>, <Literal>Float</Literal>,
-<Literal>Float#</Literal> etc.) GHC knows to import this module if you use <Function>_ccall_</Function>,
-but if you need to define your own instances of these classes, you
-will need to import <Literal>CCall</Literal> explicitly.
-</Para>
-
-<Para>
-More information on how to use <Function>_ccall_</Function> can be found in <XRef LinkEnd="glasgow-ccalls">.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>The <Literal>GlaExts</Literal> interface</Title>
-
-<Para>
-<IndexTerm><Primary>GlaExts interface (GHC extensions)</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>GlaExts</Literal> interface provides access to extensions that only GHC
-implements. These currently are: unboxed types, including the
-representations of the primitive types (Int, Float, etc.), and the
-GHC primitive operations (<Function>+#</Function>, <Function>==#</Function>, etc.).
-</Para>
-
-<Para>
-This module used to provide access to all the Glasgow extensions, but
-these have since been moved into separate libraries for compatibility
-with Hugs (version 2.09: in fact, you can still get at this stuff via
-<Literal>GlaExts</Literal> for compatibility, but this facility will likely be removed
-in the future).
-</Para>
-
-<Para>
-
-<ProgramListing>
--- the representation of some basic types:
-data Char = C# Char#
-data Int = I# Int#
-data Addr = A# Addr#
-data Word = W# Word#
-data Float = F# Float#
-data Double = D# Double#
-data Integer = S# Int# -- small integers
- | J# Int# ByteArray# -- large integers
-
-module GHC -- all primops and primitive types.
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
</Sect1>
<Sect1 id="ghc-libs-ghc">
<IndexTerm><Primary>numeric types, primitive</Primary></IndexTerm>
<IndexTerm><Primary>integer types, primitive</Primary></IndexTerm>
<IndexTerm><Primary>floating point types, primitive</Primary></IndexTerm>
-</Para>
-
-<Para>
There are the following obvious primitive types:
</Para>
</Sect2>
-<Sect2>
+<Sect2 id="sect-mutable">
<Title>Mutable arrays</Title>
<Para>
-<Anchor id="sect-mutable">
<IndexTerm><Primary>mutable arrays</Primary></IndexTerm>
<IndexTerm><Primary>arrays, mutable</Primary></IndexTerm>
-</Para>
-
-<Para>
Corresponding to <Literal>Array#</Literal> and <Literal>ByteArray#</Literal>, we have the types of
mutable versions of each. In each case, the representation is a
pointer to a suitable block of (mutable) heap-allocated storage.
</Sect2>
<Sect2>
-<Title>Stable pointers</Title>
-
-<Para>
-<IndexTerm><Primary>stable pointers</Primary></IndexTerm>
-<IndexTerm><Primary>pointers, stable</Primary></IndexTerm>
-</Para>
-
-<Para>
-A stable pointer is a name for a Haskell object which can be passed to
-the external world. It is ``stable'' in the sense that the name does
-not change when the Haskell garbage collector runs—in contrast to
-the address of the object which may well change.
-</Para>
-
-<Para>
-The stable pointer type is parameterised by the type of the thing
-which is named.
-</Para>
-
-<Para>
-
-<ProgramListing>
-type StablePtr# a
-</ProgramListing>
-
-<IndexTerm><Primary><literal>StablePtr#</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-A stable pointer is represented by an index into the (static)
-<Literal>StablePointerTable</Literal>. The Haskell garbage collector treats the
-<Literal>StablePointerTable</Literal> as a source of roots for GC.
-</Para>
-
-<Para>
-The <Function>makeStablePointer</Function> function converts a value into a stable
-pointer. It is part of the <Literal>IO</Literal> monad, because we want to be sure
-we don't allocate one twice by accident, and then only free one of the
-copies.
-</Para>
-
-<Para>
-
-<ProgramListing>
-makeStablePointer# :: a -> State# RealWorld -> (# State# RealWord, StablePtr# a #)
-freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
-deRefStablePointer# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
-</ProgramListing>
-
-<IndexTerm><Primary><literal>makeStablePointer#</literal></Primary></IndexTerm>
-<IndexTerm><Primary><literal>freeStablePointer#</literal></Primary></IndexTerm>
-<IndexTerm><Primary><literal>deRefStablePointer#</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-There is also a C procedure <Function>FreeStablePtr</Function> which frees a stable pointer.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Foreign objects</Title>
-
-<Para>
-<IndexTerm><Primary>Foreign objects</Primary></IndexTerm>
-</Para>
-
-<Para>
-A <Literal>ForeignObj#</Literal> is a reference to an object outside the Haskell world
-(i.e., from the C world, or a reference to an object on another
-machine completely.), where the Haskell world has been told ``Let me
-know when you're finished with this…''.
-</Para>
-
-<Para>
-
-<ProgramListing>
-type ForeignObj#
-</ProgramListing>
-
-<IndexTerm><Primary><literal>ForeignObj#</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-GHC provides two primitives on <Literal>ForeignObj#</Literal>:
-</Para>
-
-<Para>
-
-<ProgramListing>
-makeForeignObj#
- :: Addr# -- foreign reference
- -> Addr# -- pointer to finalisation routine
- -> (# State# RealWorld, ForeignObj# )
-writeForeignObj
- :: ForeignObj# -- foreign object
- -> Addr# -- datum
- -> State# RealWorld
- -> State# RealWorld
-</ProgramListing>
-
-<IndexTerm><Primary><literal>makeForeignObj#</literal></Primary></IndexTerm>
-<IndexTerm><Primary><literal>writeForeignObj#</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-The module <Literal>Foreign</Literal> (see library documentation) provides a more
-programmer-friendly interface to foreign objects.
-</Para>
-
-</Sect2>
-
-<Sect2>
<Title>Synchronizing variables (M-vars)</Title>
<Para>
</Sect1>
-&posix
-&libmisc
-
</Chapter>
+++ /dev/null
-<Sect1 id="Posix-library">
-<Title>The Posix library
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix library</Primary></IndexTerm>
-<IndexTerm><Primary>libraries, Posix</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>Posix</Literal> interface gives you access to the set of OS
-services standardised by POSIX 1003.1b (or the <Emphasis>IEEE Portable
-Operating System Interface for Computing Environments</Emphasis> - IEEE Std.
-1003.1). The interface is accessed by <Literal>import Posix</Literal> and
-adding <Option>-syslib posix</Option> on your command-line.
-</Para>
-
-<Sect2 id="Posix-data-types">
-<Title>Posix data types
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, data types</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-data ByteCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>ByteCount</Literal> is a primitive of type <Literal>unsigned</Literal>. At a minimum,
-an conforming implementation must support values in the range
-<Literal>[0, UINT_MAX]</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data ClockTick -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>ClockTick</Literal> is a primitive of type <Literal>clock_t</Literal>, which
-is used to measure intervals of time in fractions of a second. The
-resolution is determined by <Literal>getSysVar ClockTick</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data DeviceID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>DeviceID</Literal> is a primitive of type <Literal>dev_t</Literal>. It must
-be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>EpochTime</Literal> is a primitive of type <Literal>time_t</Literal>, which is
-used to measure seconds since the Epoch. At a minimum, the implementation
-must support values in the range <Literal>[0, INT_MAX]</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>FileID</Literal> is a primitive of type <Literal>ino_t</Literal>. It must
-be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>FileMode</Literal> is a primitive of type <Literal>mode_t</Literal>.
-It must be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>FileOffset</Literal> is a primitive of type <Literal>off_t</Literal>. It must
-be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>GroupID</Literal> is a primitive of type <Literal>gid_t</Literal>. It must
-be an arithmetic type.
-
-<ProgramListing>
-data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>Limit</Literal> is a primitive of type <Literal>long</Literal>.
-At a minimum, the implementation must support values in the range
-<Literal>[LONG_MIN, LONG_MAX]</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>LinkCount</Literal> is a primitive of type <Literal>nlink_t</Literal>. It must
-be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-type ProcessGroupID = ProcessID
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>ProcessID</Literal> is a primitive of type <Literal>pid_t</Literal>. It
-must be a signed arithmetic type.
-
-<ProgramListing>
-data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>UserID</Literal> is a primitive of type <Literal>uid_t</Literal>. It
-must be an arithmetic type.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data DirStream
-</ProgramListing>
-
-A <Literal>DirStream</Literal> is a primitive of type <Literal>DIR *</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data FileStatus
-</ProgramListing>
-
-A <Literal>FileStatus</Literal> is a primitive of type <Literal>struct stat</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data GroupEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>GroupEntry</Literal> is a primitive of type <Literal>struct group</Literal>.
-
-<ProgramListing>
-data ProcessTimes
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>ProcessTimes</Literal> is a primitive structure containing a
-<Literal>clock_t</Literal> and a <Literal>struct tms</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-An <Literal>SignalSet</Literal> is a primitive of type <Literal>sigset_t</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data SystemID
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>SystemID</Literal> is a primitive of type <Literal>struct utsname</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data TerminalAttributes
-</ProgramListing>
-
-<Literal>TerminalAttributes</Literal> is a primitive of type <Literal>struct termios</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data UserEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-A <Literal>UserEntry</Literal> is a primitive of type <Literal>struct passwd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-data BaudRate = B0 | B50 | B75 | B110 | B134 | B150 | B200 | B300 | B600
- | B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
- deriving (Eq, Show)
-
-data Fd
-
-intToFd :: Int -> Fd -- use with care.
-
-data FdOption = AppendOnWrite
- | CloseOnExec
- | NonBlockingRead
-
-data ControlCharacter = EndOfFile
- | EndOfLine
- | Erase
- | Interrupt
- | Kill
- | Quit
- | Suspend
- | Start
- | Stop
-
-type ErrorCode = Int
-
-type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
--- whence start length
-
-data FlowAction = SuspendOutput | RestartOutput | TransmitStop | TransmitStart
-
-data Handler = Default | Ignore | Catch (IO ())
-
-data LockRequest = ReadLock | WriteLock | Unlock
- deriving (Eq, Show)
-
-data OpenMode = ReadOnly | WriteOnly | ReadWrite
-
-data PathVar = LinkLimit
- | InputLineLimit
- | InputQueueLimit
- | FileNameLimit
- | PathNameLimit
- | PipeBufferLimit
- | SetOwnerAndGroupIsRestricted
- | FileNamesAreNotTruncated
-
-data QueueSelector = InputQueue | OutputQueue | BothQueues
-
-type Signal = Int
-
-data SysVar = ArgumentLimit
- | ChildLimit
- | ClockTick
- | GroupLimit
- | OpenFileLimit
- | PosixVersion
- | HasSavedIDs
- | HasJobControl
-
-data TerminalMode = InterruptOnBreak -- BRKINT
- | MapCRtoLF -- ICRNL
- | IgnoreBreak -- IGNBRK
- | IgnoreCR -- IGNCR
- | IgnoreParityErrors -- IGNPAR
- | MapLFtoCR -- INLCR
- | CheckParity -- INPCK
- | StripHighBit -- ISTRIP
- | StartStopInput -- IXOFF
- | StartStopOutput -- IXON
- | MarkParityErrors -- PARMRK
- | ProcessOutput -- OPOST
- | LocalMode -- CLOCAL
- | ReadEnable -- CREAD
- | TwoStopBits -- CSTOPB
- | HangupOnClose -- HUPCL
- | EnableParity -- PARENB
- | OddParity -- PARODD
- | EnableEcho -- ECHO
- | EchoErase -- ECHOE
- | EchoKill -- ECHOK
- | EchoLF -- ECHONL
- | ProcessInput -- ICANON
- | ExtendedFunctions -- IEXTEN
- | KeyboardInterrupts -- ISIG
- | NoFlushOnInterrupt -- NOFLSH
- | BackgroundWriteInterrupt -- TOSTOP
-
-data TerminalState = Immediately | WhenDrained | WhenFlushed
-
-data ProcessStatus = Exited ExitCode
- | Terminated Signal
- | Stopped Signal
- deriving (Eq, Show)
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="Process-Primitives">
-<Title>Posix Process Primitives
-</Title>
-
-<Para>
-
-<ProgramListing>
-forkProcess :: IO (Maybe ProcessID)
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>forkProcess</Function> calls <Function>fork</Function>, returning
-<Literal>Just pid</Literal> to the parent, where <VarName>pid</VarName> is the
-ProcessID of the child, and returning <Literal>Nothing</Literal> to the
-child.
-</Para>
-
-<Para>
-
-<ProgramListing>
-executeFile :: FilePath -- Command
- -> Bool -- Search PATH?
- -> [String] -- Arguments
- -> Maybe [(String, String)] -- Environment
- -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>executeFile cmd args env</Literal> calls one of the
-<Function>execv*</Function> family, depending on whether or not the current
-PATH is to be searched for the command, and whether or not an
-environment is provided to supersede the process's current
-environment. The basename (leading directory names suppressed) of
-the command is passed to <Function>execv*</Function> as <VarName>arg[0]</VarName>;
-the argument list passed to <Function>executeFile</Function> therefore begins with <VarName>arg[1]</VarName>.
-</Para>
-
-<Para>
-
-<Screen>
-Search PATH? Supersede environ? Call
-~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~ ~~~~~~~
-False False execv
-False True execve
-True False execvp
-True True execvpe*
-</Screen>
-
-</Para>
-
-<Para>
-Note that <Function>execvpe</Function> is not provided by the POSIX standard, and must
-be written by hand. Care must be taken to ensure that the search path
-is extracted from the original environment, and not from the
-environment to be passed on to the new image.
-</Para>
-
-<Para>
-NOTE: In general, sharing open files between parent and child
-processes is potential bug farm, and should be avoided unless you
-really depend on this `feature' of POSIX' <Function>fork()</Function> semantics. Using
-Haskell, there's the extra complication that arguments to
-<Function>executeFile</Function> might come from files that are read lazily (using
-<Function>hGetContents</Function>, or some such.) If this is the case, then for your own
-sanity, please ensure that the arguments to <Function>executeFile</Function> have been
-fully evaluated before calling <Function>forkProcess</Function> (followed by
-<Function>executeFile</Function>.) Consider yourself warned :-)
-</Para>
-
-<Para>
-A successful <Function>executeFile</Function> overlays the current process image with
-a new one, so it only returns on failure.
-</Para>
-
-<Para>
-
-<ProgramListing>
-runProcess :: FilePath -- Command
- -> [String] -- Arguments
- -> Maybe [(String, String)] -- Environment (Nothing -> Inherited)
- -> Maybe FilePath -- Working directory (Nothing -> inherited)
- -> Maybe Handle -- stdin (Nothing -> inherited)
- -> Maybe Handle -- stdout (Nothing -> inherited)
- -> Maybe Handle -- stderr (Nothing -> inherited)
- -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>runProcess</Function> is our candidate for the high-level OS-independent
-primitive.
-</Para>
-
-<Para>
-<Literal>runProcess cmd args env wd inhdl outhdl errhdl</Literal> runs <Command>cmd</Command>
-(searching the current <Literal>PATH</Literal>) with arguments <Literal>args</Literal>. If
-<Literal>env</Literal> is <Literal>Just pairs</Literal>, the command is executed with the
-environment specified by <Literal>pairs</Literal> of variables and values;
-otherwise, the command is executed with the current environment. If
-<Literal>wd</Literal> is <Literal>Just dir</Literal>, the command is executed with working
-directory <Literal>dir</Literal>; otherwise, the command is executed in the current
-working directory. If <Literal>{in,out,err</Literal>hdl} is <Literal>Just handle</Literal>, the
-command is executed with the <Literal>Fd</Literal> for <Literal>std{in,out,err</Literal>}
-attached to the specified <Literal>handle</Literal>; otherwise, the <Literal>Fd</Literal> for
-<Literal>std{in,out,err</Literal>} is left unchanged.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> ProcessID
- -> IO (Maybe ProcessStatus)
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getProcessStatus blk stopped pid</Literal> calls <Function>waitpid</Function>, returning
-<Literal>Just tc</Literal>, the <Literal>ProcessStatus</Literal> for process <Literal>pid</Literal> if it is
-available, <Literal>Nothing</Literal> otherwise. If <Literal>blk</Literal> is <Literal>False</Literal>, then
-<Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
-If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
-options for <Function>waitpid</Function>, otherwise not.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getGroupProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> ProcessGroupID
- -> IO (Maybe (ProcessID, ProcessStatus))
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getGroupProcessStatus blk stopped pgid</Literal> calls <Function>waitpid</Function>,
-returning <Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and
-<Literal>ProcessStatus</Literal> for any process in group <Literal>pgid</Literal> if one is
-available, <Literal>Nothing</Literal> otherwise. If <Literal>blk</Literal> is <Literal>False</Literal>, then
-<Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
-If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
-options for <Function>waitpid</Function>, otherwise not.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getAnyProcessStatus :: Bool -- Block?
- -> Bool -- Stopped processes?
- -> IO (Maybe (ProcessID, ProcessStatus))
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getAnyProcessStatus blk stopped</Literal> calls <Function>waitpid</Function>, returning
-<Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and <Literal>ProcessStatus</Literal> for any
-child process if one is available, <Literal>Nothing</Literal> otherwise. If
-<Literal>blk</Literal> is <Literal>False</Literal>, then <Literal>WNOHANG</Literal> is set in the options for
-<Function>waitpid</Function>, otherwise not. If <Literal>stopped</Literal> is <Literal>True</Literal>, then
-<Literal>WUNTRACED</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
-</Para>
-
-<Para>
-
-<ProgramListing>
-exitImmediately :: ExitCode -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>exitImmediately status</Literal> calls <Function>_exit</Function> to terminate the process
-with the indicated exit <Literal>status</Literal>.
-The operation never returns.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getEnvironment :: IO [(String, String)]
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getEnvironment</Function> parses the environment variable mapping provided by
-<Literal>environ</Literal>, returning <Literal>(variable, value)</Literal> pairs.
-The operation never fails.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setEnvironment :: [(String, String)] -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>setEnvironment</Function> replaces the process environment with the provided
-mapping of <Literal>(variable, value)</Literal> pairs.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getEnvVar :: String -> IO String
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getEnvVar var</Literal> returns the value associated with variable <VarName>var</VarName>
-in the current environment (identical functionality provided through
-standard Haskell library function <Function>System.getEnv</Function>).
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-The variable has no mapping in the current environment.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-setEnvVar :: String -> String -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setEnvVar var val</Literal> sets the value associated with variable <VarName>var</VarName>
-in the current environment to be <Literal>val</Literal>. Any previous mapping is
-superseded.
-</Para>
-
-<Para>
-
-<ProgramListing>
-removeEnvVar :: String -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>removeEnvVar var</Literal> removes any value associated with variable <VarName>var</VarName>
-in the current environment. Deleting a variable for which there is no mapping
-does not generate an error.
-</Para>
-
-<Para>
-
-<ProgramListing>
-nullSignal :: Signal
-nullSignal = 0
-
-backgroundRead, sigTTIN :: Signal
-backgroundWrite, sigTTOU :: Signal
-continueProcess, sigCONT :: Signal
-floatingPointException, sigFPE :: Signal
-illegalInstruction, sigILL :: Signal
-internalAbort, sigABRT :: Signal
-keyboardSignal, sigINT :: Signal
-keyboardStop, sigTSTP :: Signal
-keyboardTermination, sigQUIT :: Signal
-killProcess, sigKILL :: Signal
-lostConnection, sigHUP :: Signal
-openEndedPipe, sigPIPE :: Signal
-processStatusChanged, sigCHLD :: Signal
-realTimeAlarm, sigALRM :: Signal
-segmentationViolation, sigSEGV :: Signal
-softwareStop, sigSTOP :: Signal
-softwareTermination, sigTERM :: Signal
-userDefinedSignal1, sigUSR1 :: Signal
-userDefinedSignal2, sigUSR2 :: Signal
-
-signalProcess :: Signal -> ProcessID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>signalProcess int pid</Literal> calls <Function>kill</Function> to signal
-process <Literal>pid</Literal> with interrupt signal <Literal>int</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-raiseSignal :: Signal -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>raiseSignal int</Literal> calls <Function>kill</Function> to signal the current process
-with interrupt signal <Literal>int</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>signalProcessGroup int pgid</Literal> calls <Function>kill</Function> to signal
-all processes in group <Literal>pgid</Literal> with interrupt signal <Literal>int</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setStoppedChildFlag :: Bool -> IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setStoppedChildFlag bool</Literal> sets a flag which controls whether or
-not the <Constant>NOCLDSTOP</Constant> option will be used the next time a signal
-handler is installed for <Constant>SIGCHLD</Constant>. If <Literal>bool</Literal> is <Literal>True</Literal> (the
-default), <Constant>NOCLDSTOP</Constant> will not be used; otherwise it will be. The
-operation never fails.
-</Para>
-
-<Para>
-
-<ProgramListing>
-queryStoppedChildFlag :: IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>queryStoppedChildFlag</Function> queries the flag which
-controls whether or not the <Constant>NOCLDSTOP</Constant> option will be used
-the next time a signal handler is installed for <Constant>SIGCHLD</Constant>.
-If <Constant>NOCLDSTOP</Constant> will be used, it returns <Literal>False</Literal>;
-otherwise (the default) it returns <Literal>True</Literal>.
-The operation never fails.
-</Para>
-
-<Para>
-
-<ProgramListing>
-emptySignalSet :: SignalSet
-fullSignalSet :: SignalSet
-addSignal :: Signal -> SignalSet -> SignalSet
-deleteSignal :: Signal -> SignalSet -> SignalSet
-inSignalSet :: Signal -> SignalSet -> Bool
-
-installHandler :: Signal
- -> Handler
- -> Maybe SignalSet -- other signals to block
- -> IO Handler -- old handler
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>installHandler int handler iset</Literal> calls <Constant>sigaction</Constant> to install an
-interrupt handler for signal <Literal>int</Literal>. If <Literal>handler</Literal> is <Literal>Default</Literal>,
-<Constant>SIG_DFL</Constant> is installed; if <Literal>handler</Literal> is <Literal>Ignore</Literal>, <Constant>SIG_IGN</Constant> is
-installed; if <Literal>handler</Literal> is <Literal>Catch action</Literal>, a handler is installed
-which will invoke <Literal>action</Literal> in a new thread when (or shortly after) the
-signal is received. See <XRef LinkEnd="concurrent-haskell"> for details on how to communicate between
-threads.
-</Para>
-
-<Para>
-If <Literal>iset</Literal> is <Literal>Just s</Literal>, then the <VarName>sa_mask</VarName> of the <Literal>sigaction</Literal> structure
-is set to <Literal>s</Literal>; otherwise it is cleared. The previously installed
-signal handler for <Literal>int</Literal> is returned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getSignalMask :: IO SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getSignalMask</Function> calls <Function>sigprocmask</Function> to determine the
-set of interrupts which are currently being blocked.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setSignalMask :: SignalSet -> IO SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
-<Constant>SIG_SETMASK</Constant> to block all interrupts in <Literal>mask</Literal>. The
-previous set of blocked interrupts is returned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-blockSignals :: SignalSet -> IO SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
-<Constant>SIG_BLOCK</Constant> to add all interrupts in <Literal>mask</Literal> to the
-set of blocked interrupts. The previous set of blocked interrupts is returned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-unBlockSignals :: SignalSet -> IO SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
-<Constant>SIG_UNBLOCK</Constant> to remove all interrupts in <Literal>mask</Literal> from the
-set of blocked interrupts. The previous set of blocked interrupts is returned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getPendingSignals :: IO SignalSet
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getPendingSignals</Function> calls <Function>sigpending</Function> to obtain
-the set of interrupts which have been received but are currently blocked.
-</Para>
-
-<Para>
-
-<ProgramListing>
-awaitSignal :: Maybe SignalSet -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>awaitSignal iset</Literal> suspends execution until an interrupt is received.
-If <Literal>iset</Literal> is <Literal>Just s</Literal>, <Function>awaitSignal</Function> calls <Function>sigsuspend</Function>, installing
-<Literal>s</Literal> as the new signal mask before suspending execution; otherwise, it
-calls <Function>pause</Function>. <Function>awaitSignal</Function> returns on receipt of a signal. If you
-have installed any signal handlers with <Function>installHandler</Function>, it may be
-wise to call <Function>yield</Function> directly after <Function>awaitSignal</Function> to ensure that the
-signal handler runs as promptly.
-</Para>
-
-<Para>
-
-<ProgramListing>
-scheduleAlarm :: Int -> IO Int
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>scheduleAlarm i</Literal> calls <Function>alarm</Function> to schedule a real time
-alarm at least <Literal>i</Literal> seconds in the future.
-</Para>
-
-<Para>
-
-<ProgramListing>
-sleep :: Int -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>sleep i</Literal> calls <Function>sleep</Function> to suspend execution of the
-program until at least <Literal>i</Literal> seconds have elapsed or a signal is
-received.
-</Para>
-
-</Sect2>
-
-<Sect2 id="Process-Environment">
-<Title>Posix Process Environment
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, process environment</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getProcessID :: IO ProcessID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getProcessID</Function> calls <Function>getpid</Function> to obtain the <Literal>ProcessID</Literal> for
-the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getParentProcessID :: IO ProcessID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getProcessID</Function> calls <Function>getppid</Function> to obtain the <Literal>ProcessID</Literal> for
-the parent of the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getRealUserID :: IO UserID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getRealUserID</Function> calls <Function>getuid</Function> to obtain the real <Literal>UserID</Literal>
-associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getEffectiveUserID :: IO UserID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getRealUserID</Function> calls <Function>geteuid</Function> to obtain the effective
-<Literal>UserID</Literal> associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setUserID :: UserID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setUserID uid</Literal> calls <Function>setuid</Function> to set the real, effective, and
-saved set-user-id associated with the current process to <Literal>uid</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getLoginName :: IO String
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getLoginName</Function> calls <Function>getlogin</Function> to obtain the login name
-associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getRealGroupID :: IO GroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getRealGroupID</Function> calls <Function>getgid</Function> to obtain the real <Literal>GroupID</Literal>
-associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getEffectiveGroupID :: IO GroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getEffectiveGroupID</Function> calls <Function>getegid</Function> to obtain the effective
-<Literal>GroupID</Literal> associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setGroupID :: GroupID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setGroupID gid</Literal> calls <Function>setgid</Function> to set the real, effective, and
-saved set-group-id associated with the current process to <Literal>gid</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getGroups :: IO [GroupID]
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getGroups</Function> calls <Function>getgroups</Function> to obtain the list of
-supplementary <Literal>GroupID</Literal>s associated with the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getEffectiveUserName :: IO String
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getEffectiveUserName</Function> calls <Function>cuserid</Function> to obtain a name
-associated with the effective <Literal>UserID</Literal> of the process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getProcessGroupID :: IO ProcessGroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getProcessGroupID</Function> calls <Function>getpgrp</Function> to obtain the
-<Literal>ProcessGroupID</Literal> for the current process.
-</Para>
-
-<Para>
-
-<ProgramListing>
-createProcessGroup :: ProcessID -> IO ProcessGroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>createProcessGroup pid</Literal> calls <Function>setpgid</Function> to make
-process <Literal>pid</Literal> a new process group leader.
-</Para>
-
-<Para>
-
-<ProgramListing>
-joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>joinProcessGroup pgid</Literal> calls <Function>setpgid</Function> to set the
-<Literal>ProcessGroupID</Literal> of the current process to <Literal>pgid</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setProcessGroupID pid pgid</Literal> calls <Function>setpgid</Function> to set the
-<Literal>ProcessGroupID</Literal> for process <Literal>pid</Literal> to <Literal>pgid</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-createSession :: IO ProcessGroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>createSession</Function> calls <Function>setsid</Function> to create a new session
-with the current process as session leader.
-</Para>
-
-<Para>
-
-<ProgramListing>
-systemName :: SystemID -> String
-nodeName :: SystemID -> String
-release :: SystemID -> String
-version :: SystemID -> String
-machine :: SystemID -> String
-
-getSystemID :: IO SystemID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getSystemID</Function> calls <Function>uname</Function> to obtain information
-about the current operating system.
-</Para>
-
-<Para>
-
-<ProgramListing>
-> epochTime :: IO EpochTime
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>epochTime</Function> calls <Function>time</Function> to obtain the number of
-seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
-</Para>
-
-<Para>
-
-<ProgramListing>
-elapsedTime :: ProcessTimes -> ClockTick
-userTime :: ProcessTimes -> ClockTick
-systemTime :: ProcessTimes -> ClockTick
-childUserTime :: ProcessTimes -> ClockTick
-childSystemTime :: ProcessTimes -> ClockTick
-
-getProcessTimes :: IO ProcessTimes
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getProcessTimes</Function> calls <Function>times</Function> to obtain time-accounting
-information for the current process and its children.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getControllingTerminalName :: IO FilePath
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getControllingTerminalName</Function> calls <Function>ctermid</Function> to obtain
-a name associated with the controlling terminal for the process. If a
-controlling terminal exists,
-<Function>getControllingTerminalName</Function> returns the name of the
-controlling terminal.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-There is no controlling terminal, or its name cannot be determined.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getTerminalName :: Fd -> IO FilePath
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getTerminalName fd</Literal> calls <Function>ttyname</Function> to obtain a name associated
-with the terminal for <Literal>Fd</Literal> <Literal>fd</Literal>. If <Literal>fd</Literal> is associated
-with a terminal, <Function>getTerminalName</Function> returns the name of the
-terminal.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>InappropriateType</Literal></Term>
-<ListItem>
-<Para>
-The channel is not associated with a terminal.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-The channel is associated with a terminal, but it has no name.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-queryTerminal :: Fd -> IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>queryTerminal fd</Literal> calls <Function>isatty</Function> to determine whether or
-not <Literal>Fd</Literal> <Literal>fd</Literal> is associated with a terminal.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getSysVar :: SysVar -> IO Limit
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getSysVar var</Literal> calls <Function>sysconf</Function> to obtain the
-dynamic value of the requested configurable system limit or option.
-For defined system limits, <Function>getSysVar</Function> returns the associated
-value. For defined system options, the result of <Function>getSysVar</Function>
-is undefined, but not failure.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-The requested system limit or option is undefined.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="Files-and-Directories">
-<Title>Posix operations on files and directories
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, files and directories</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-openDirStream :: FilePath -> IO DirStream
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>openDirStream dir</Literal> calls <Function>opendir</Function> to obtain a
-directory stream for <Literal>dir</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-readDirStream :: DirStream -> IO String
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>readDirStream dp</Literal> calls <Function>readdir</Function> to obtain the
-next directory entry (<Literal>struct dirent</Literal>) for the open directory
-stream <Literal>dp</Literal>, and returns the <VarName>d_name</VarName> member of that
-structure.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>EOF</Literal></Term>
-<ListItem>
-<Para>
-End of file has been reached.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-rewindDirStream :: DirStream -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>rewindDirStream dp</Literal> calls <Function>rewinddir</Function> to reposition
-the directory stream <Literal>dp</Literal> at the beginning of the directory.
-</Para>
-
-<Para>
-
-<ProgramListing>
-closeDirStream :: DirStream -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>closeDirStream dp</Literal> calls <Function>closedir</Function> to close
-the directory stream <Literal>dp</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getWorkingDirectory :: IO FilePath
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getWorkingDirectory</Function> calls <Function>getcwd</Function> to obtain the name
-of the current working directory.
-</Para>
-
-<Para>
-
-<ProgramListing>
-changeWorkingDirectory :: FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>changeWorkingDirectory dir</Literal> calls <Function>chdir</Function> to change
-the current working directory to <Literal>dir</Literal>.
-</Para>
-
-<Para>
-<ProgramListing>
-nullFileMode :: FileMode -- ---------
-ownerReadMode :: FileMode -- r--------
-ownerWriteMode :: FileMode -- -w-------
-ownerExecuteMode :: FileMode -- --x------
-groupReadMode :: FileMode -- ---r-----
-groupWriteMode :: FileMode -- ----w----
-groupExecuteMode :: FileMode -- -----x---
-otherReadMode :: FileMode -- ------r--
-otherWriteMode :: FileMode -- -------w-
-otherExecuteMode :: FileMode -- --------x
-setUserIDMode :: FileMode -- --S------
-setGroupIDMode :: FileMode -- -----S---
-
-stdFileMode :: FileMode -- rw-rw-rw-
-
-ownerModes :: FileMode -- rwx------
-groupModes :: FileMode -- ---rwx---
-otherModes :: FileMode -- ------rwx
-accessModes :: FileMode -- rwxrwxrwx
-
-unionFileModes :: FileMode -> FileMode -> FileMode
-intersectFileModes :: FileMode -> FileMode -> FileMode
-
-stdInput :: Fd
-stdInput = intToFd 0
-
-stdOutput :: Fd
-stdOutput = intToFd 1
-
-stdError :: Fd
-stdError = intToFd 2
-
-data OpenFileFlags =
- OpenFileFlags {
- append :: Bool,
- exclusive :: Bool,
- noctty :: Bool,
- nonBlock :: Bool,
- trunc :: Bool
- }
-
-openFd :: FilePath
- -> OpenMode
- -> Maybe FileMode -- Just x => O_CREAT, Nothing => must exist
- -> OpenFileFlags
- -> IO Fd
-</ProgramListing>
-</Para>
-
-<Para>
-<Literal>openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)</Literal> calls
-<Function>open</Function> to obtain a <Literal>Fd</Literal> for the file <Literal>path</Literal> with access
-mode <Literal>acc</Literal>. If <Literal>mode</Literal> is <Literal>Just m</Literal>, the <Constant>O_CREAT</Constant> flag is
-set and the file's permissions will be based on <Literal>m</Literal> if it does not
-already exist; otherwise, the <Constant>O_CREAT</Constant> flag is not set. The
-arguments <Literal>app</Literal>, <Literal>excl</Literal>, <Literal>noctty</Literal>, <Literal>nonblock</Literal>, and
-<Literal>trunc</Literal> control whether or not the flags <Constant>O_APPEND</Constant>,
-<Constant>O_EXCL</Constant>, <Constant>O_NOCTTY</Constant>, <Constant>O_NONBLOCK</Constant>, and <Constant>O_TRUNC</Constant> are set,
-respectively.
-</Para>
-
-<Para>
-
-<ProgramListing>
-createFile :: FilePath -> FileMode -> IO Fd
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>createFile path mode</Literal> calls <Function>creat</Function> to obtain a <Literal>Fd</Literal>
-for file <Literal>path</Literal>, which will be created with permissions based on
-<Literal>mode</Literal> if it does not already exist.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setFileCreationMask :: FileMode -> IO FileMode
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setFileCreationMask mode</Literal> calls <Function>umask</Function> to set
-the process's file creation mask to <Literal>mode</Literal>. The previous file
-creation mask is returned.
-</Para>
-
-<Para>
-
-<ProgramListing>
-createLink :: FilePath -> FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>createLink old new</Literal> calls <Function>link</Function> to create a
-new path, <Literal>new</Literal>, linked to an existing file, <Literal>old</Literal>.
-
-<ProgramListing>
-createDirectory :: FilePath -> FileMode -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>createDirectory dir mode</Literal> calls <Function>mkdir</Function> to
-create a new directory, <Literal>dir</Literal>, with permissions based on
-<Literal>mode</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-createNamedPipe :: FilePath -> FileMode -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>createNamedPipe fifo mode</Literal> calls <Function>mkfifo</Function> to
-create a new named pipe, <Literal>fifo</Literal>, with permissions based on
-<Literal>mode</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-removeLink :: FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>removeLink path</Literal> calls <Function>unlink</Function> to remove the link
-named <Literal>path</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-removeDirectory :: FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>removeDirectory dir</Literal> calls <Function>rmdir</Function> to remove the
-directory named <Literal>dir</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-rename :: FilePath -> FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>rename old new</Literal> calls <Function>rename</Function> to rename a
-file or directory from <Literal>old</Literal> to <Literal>new</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-fileMode :: FileStatus -> FileMode
-
-fileID :: FileStatus -> FileID
-deviceID :: FileStatus -> DeviceID
-
-linkCount :: FileStatus -> LinkCount
-
-fileOwner :: FileStatus -> UserID
-fileGroup :: FileStatus -> GroupID
-fileSize :: FileStatus -> FileOffset
-
-accessTime :: FileStatus -> EpochTime
-modificationTime :: FileStatus -> EpochTime
-statusChangeTime :: FileStatus -> EpochTime
-
-isDirectory :: FileStatus -> Bool
-isCharacterDevice :: FileStatus -> Bool
-isBlockDevice :: FileStatus -> Bool
-isRegularFile :: FileStatus -> Bool
-isNamedPipe :: FileStatus -> Bool
-
-getFileStatus :: FilePath -> IO FileStatus
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getFileStatus path</Literal> calls <Function>stat</Function> to get the
-<Literal>FileStatus</Literal> information for the file <Literal>path</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getFdStatus :: Fd -> IO FileStatus
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getFdStatus fd</Literal> calls <Function>fstat</Function> to get the
-<Literal>FileStatus</Literal> information for the file associated with
-<Literal>Fd</Literal> <Literal>fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>queryAccess path r w x</Literal> calls <Function>access</Function> to test the access
-permissions for file <Literal>path</Literal>. The three arguments, <Literal>r</Literal>, <Literal>w</Literal>,
-and <Literal>x</Literal> control whether or not <Function>access</Function> is called with
-<Constant>R_OK</Constant>, <Constant>W_OK</Constant>, and <Constant>X_OK</Constant> respectively.
-</Para>
-
-<Para>
-
-<ProgramListing>
-queryFile :: FilePath -> IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>queryFile path</Literal> calls <Function>access</Function> with <Constant>F_OK</Constant> to test for the
-existence for file <Literal>path</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setFileMode :: FilePath -> FileMode -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setFileMode path mode</Literal> calls <Function>chmod</Function> to set the
-permission bits associated with file <Literal>path</Literal> to <Literal>mode</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setOwnerAndGroup path uid gid</Literal> calls <Function>chown</Function> to
-set the <Literal>UserID</Literal> and <Literal>GroupID</Literal> associated with file
-<Literal>path</Literal> to <Literal>uid</Literal> and <Literal>gid</Literal>, respectively.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setFileTimes path atime mtime</Literal> calls <Function>utime</Function> to
-set the access and modification times associated with file
-<Literal>path</Literal> to <Literal>atime</Literal> and <Literal>mtime</Literal>, respectively.
-</Para>
-
-<Para>
-
-<ProgramListing>
-touchFile :: FilePath -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>touchFile path</Literal> calls <Function>utime</Function> to
-set the access and modification times associated with file
-<Literal>path</Literal> to the current time.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getPathVar :: PathVar -> FilePath -> IO Limit
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getPathVar var path</Literal> calls <Function>pathconf</Function> to obtain the
-dynamic value of the requested configurable file limit or option associated
-with file or directory <Literal>path</Literal>. For
-defined file limits, <Function>getPathVar</Function> returns the associated
-value. For defined file options, the result of <Function>getPathVar</Function>
-is undefined, but not failure.
-The operation may fail with:
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-The requested file limit or option is undefined.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getFdVar :: PathVar -> Fd -> IO Limit
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getFdVar var fd</Literal> calls <Function>fpathconf</Function> to obtain the
-dynamic value of the requested configurable file limit or option associated
-with the file or directory attached to the open channel <Literal>fd</Literal>.
-For defined file limits, <Function>getFdVar</Function> returns the associated
-value. For defined file options, the result of <Function>getFdVar</Function>
-is undefined, but not failure.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-The requested file limit or option is undefined.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="Input-Output">
-<Title>Posix Input and Output Primitives
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, input/output</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-createPipe :: IO (Fd, Fd)
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>createPipe</Function> calls <Function>pipe</Function> to create a pipe and returns a pair of
-<Literal>Fd</Literal>s, the first for reading and the second for writing.
-</Para>
-
-<Para>
-
-<ProgramListing>
-dup :: Fd -> IO Fd
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>dup fd</Literal> calls <Function>dup</Function> to duplicate <Literal>Fd</Literal> <Literal>fd</Literal> to
-another <Literal>Fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-dupTo :: Fd -> Fd -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>dupTo src dst</Literal> calls <Function>dup2</Function> to duplicate <Literal>Fd</Literal>
-<Literal>src</Literal> to <Literal>Fd</Literal> <Literal>dst</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-fdClose :: Fd -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>fdClose fd</Literal> calls <Function>close</Function> to close <Literal>Fd</Literal> <Literal>fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>fdRead fd nbytes</Literal> calls <Function>read</Function> to read at most <Literal>nbytes</Literal>
-bytes from <Literal>Fd</Literal> <Literal>fd</Literal>, and returns the result as a string
-paired with the number of bytes actually read.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>EOF</Literal></Term>
-<ListItem>
-<Para>
-End of file has been reached.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>SystemError</Literal></Term>
-<ListItem>
-<Para>
-Various other causes.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-fdWrite :: Fd -> String -> IO ByteCount
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>fdWrite fd s</Literal> calls <Function>write</Function> to write
-the string <Literal>s</Literal> to <Literal>Fd</Literal> <Literal>fd</Literal> as a
-contiguous sequence of bytes. It returns the number of bytes successfully
-written.
-</Para>
-
-<Para>
-
-<ProgramListing>
-queryFdOption :: FdOption -> Fd -> IO Bool
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getFdOption opt fd</Literal> calls <Function>fcntl</Function> to determine whether or
-not the flag associated with <Literal>FdOption</Literal> <Literal>opt</Literal> is set for
-<Literal>Fd</Literal> <Literal>fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setFdOption :: Fd -> FdOption -> Bool -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setFdOption fd opt val</Literal> calls <Function>fcntl</Function> to set the flag
-associated with <Literal>FdOption</Literal> <Literal>opt</Literal> on <Literal>Fd</Literal> <Literal>fd</Literal> to
-<Literal>val</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getLock fd lock</Literal> calls <Function>fcntl</Function> to get the first <Literal>FileLock</Literal>
-for <Literal>Fd</Literal> <Literal>fd</Literal> which blocks the <Literal>FileLock</Literal> <Literal>lock</Literal>. If
-no such <Literal>FileLock</Literal> exists, <Function>getLock</Function> returns <Literal>Nothing</Literal>.
-Otherwise, it returns <Literal>Just (pid, block)</Literal>, where <Literal>block</Literal> is the
-blocking <Literal>FileLock</Literal> and <Literal>pid</Literal> is the <Literal>ProcessID</Literal> of the
-process holding the blocking <Literal>FileLock</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setLock :: Fd -> FileLock -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F_SETLK</Constant> to set or
-clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
-<Literal>FileLock</Literal> <Literal>lock</Literal>. <Function>setLock</Function> does not block, but fails with
-<Literal>SystemError</Literal> if the request cannot be satisfied immediately.
-</Para>
-
-<Para>
-
-<ProgramListing>
-waitToSetLock :: Fd -> FileLock -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>waitToSetLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F_SETLKW</Constant> to set
-or clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
-<Literal>FileLock</Literal> <Literal>lock</Literal>. If the request cannot be satisfied
-immediately, <Function>waitToSetLock</Function> blocks until the request can be
-satisfied.
-</Para>
-
-<Para>
-
-<ProgramListing>
-fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>fdSeek fd whence offset</Literal> calls <Function>lseek</Function> to position the
-<Literal>Fd</Literal> <Literal>fd</Literal> at the given <Literal>offset</Literal> from the starting location
-indicated by <Literal>whence</Literal>. It returns the resulting offset from the
-start of the file in bytes.
-</Para>
-
-</Sect2>
-
-<Sect2 id="Device-Specific-Functions">
-<Title>Posix, Device- and Class-Specific Functions
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, device and class-specific functions</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-terminalMode :: TerminalMode -> TerminalAttributes -> Bool
-withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
-withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
-
-bitsPerByte :: TerminalAttributes -> Int
-withBits :: TerminalAttributes -> Int -> TerminalAttributes
-
-controlChar :: TerminalAttributes -> ControlCharacter -> Maybe Char
-withCC :: TerminalAttributes
- -> (ControlCharacter, Char)
- -> TerminalAttributes
-withoutCC :: TerminalAttributes
- -> ControlCharacter
- -> TerminalAttributes
-
-inputTime :: TerminalAttributes -> Int
-withTime :: TerminalAttributes -> Int -> TerminalAttributes
-
-minInput :: TerminalAttributes -> Int
-withMinInput :: TerminalAttributes -> Int -> TerminalAttributes
-
-inputSpeed :: TerminalAttributes -> BaudRate
-withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
-
-outputSpeed :: TerminalAttributes -> BaudRate
-withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
-
-getTerminalAttributes :: Fd -> IO TerminalAttributes
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getTerminalAttributes fd</Literal> calls <Function>tcgetattr</Function> to obtain
-the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setTerminalAttributes :: Fd
- -> TerminalAttributes
- -> TerminalState
- -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setTerminalAttributes fd attr ts</Literal> calls <Function>tcsetattr</Function> to change
-the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal> to
-<Literal>attr</Literal>, when the terminal is in the state indicated by <Literal>ts</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-sendBreak :: Fd -> Int -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>sendBreak fd duration</Literal> calls <Function>tcsendbreak</Function> to transmit a
-continuous stream of zero-valued bits on <Literal>Fd</Literal> <Literal>fd</Literal> for the
-specified implementation-dependent <Literal>duration</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-drainOutput :: Fd -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>drainOutput fd</Literal> calls <Function>tcdrain</Function> to block until all output
-written to <Literal>Fd</Literal> <Literal>fd</Literal> has been transmitted.
-</Para>
-
-<Para>
-
-<ProgramListing>
-discardData :: Fd -> QueueSelector -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>discardData fd queues</Literal> calls <Function>tcflush</Function> to discard
-pending input and/or output for <Literal>Fd</Literal> <Literal>fd</Literal>,
-as indicated by the <Literal>QueueSelector</Literal> <Literal>queues</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-controlFlow :: Fd -> FlowAction -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>controlFlow fd action</Literal> calls <Function>tcflow</Function> to control the
-flow of data on <Literal>Fd</Literal> <Literal>fd</Literal>, as indicated by
-<Literal>action</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getTerminalProcessGroupID fd</Literal> calls <Function>tcgetpgrp</Function> to
-obtain the <Literal>ProcessGroupID</Literal> of the foreground process group
-associated with the terminal attached to <Literal>Fd</Literal> <Literal>fd</Literal>.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setTerminalProcessGroupID fd pgid</Literal> calls <Function>tcsetpgrp</Function> to
-set the <Literal>ProcessGroupID</Literal> of the foreground process group
-associated with the terminal attached to <Literal>Fd</Literal>
-<Literal>fd</Literal> to <Literal>pgid</Literal>.
-</Para>
-
-</Sect2>
-
-<Sect2 id="System-Database">
-<Title>Posix System Databases
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, system databases</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-groupName :: GroupEntry -> String
-groupID :: GroupEntry -> GroupID
-groupMembers :: GroupEntry -> [String]
-
-getGroupEntryForID :: GroupID -> IO GroupEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getGroupEntryForID gid</Literal> calls <Function>getgrgid</Function> to obtain
-the <Literal>GroupEntry</Literal> information associated with <Literal>GroupID</Literal>
-<Literal>gid</Literal>.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-There is no group entry for the GroupID.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getGroupEntryForName :: String -> IO GroupEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getGroupEntryForName name</Literal> calls <Function>getgrnam</Function> to obtain
-the <Literal>GroupEntry</Literal> information associated with the group called
-<Literal>name</Literal>.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-There is no group entry for the name.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-userName :: UserEntry -> String
-userID :: UserEntry -> UserID
-userGroupID :: UserEntry -> GroupID
-homeDirectory :: UserEntry -> String
-userShell :: UserEntry -> String
-
-getUserEntryForID :: UserID -> IO UserEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getUserEntryForID gid</Literal> calls <Function>getpwuid</Function> to obtain
-the <Literal>UserEntry</Literal> information associated with <Literal>UserID</Literal>
-<Literal>uid</Literal>.
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-There is no user entry for the UserID.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getUserEntryForName :: String -> IO UserEntry
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>getUserEntryForName name</Literal> calls <Function>getpwnam</Function> to obtain
-the <Literal>UserEntry</Literal> information associated with the user login
-<Literal>name</Literal>.
-</Para>
-
-<Para>
-The operation may fail with:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>NoSuchThing</Literal></Term>
-<ListItem>
-<Para>
-There is no user entry for the name.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="Error-reporting-and-handling">
-<Title>POSIX Errors
-</Title>
-
-<Para>
-<IndexTerm><Primary>Posix, errors</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-getErrorCode :: IO ErrorCode
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Function>getErrorCode</Function> returns the current value of the external
-variable <Function>errno</Function>. It never fails.
-</Para>
-
-<Para>
-
-<ProgramListing>
-setErrorCode :: ErrorCode -> IO ()
-</ProgramListing>
-
-</Para>
-
-<Para>
-<Literal>setErrorCode err</Literal> sets the external
-variable <Function>errno</Function> to <Literal>err</Literal>. It never fails.
-</Para>
-
-<Para>
-
-<ProgramListing>
-noError :: ErrorCode
-noError = 0
-
-argumentListTooLong, e2BIG :: ErrorCode
-badFd, eBADF :: ErrorCode
-brokenPipe, ePIPE :: ErrorCode
-directoryNotEmpty, eNOTEMPTY :: ErrorCode
-execFormatError, eNOEXEC :: ErrorCode
-fileAlreadyExists, eEXIST :: ErrorCode
-fileTooLarge, eFBIG :: ErrorCode
-filenameTooLong, eNAMETOOLONG :: ErrorCode
-improperLink, eXDEV :: ErrorCode
-inappropriateIOControlOperation, eNOTTY :: ErrorCode
-inputOutputError, eIO :: ErrorCode
-interruptedOperation, eINTR :: ErrorCode
-invalidArgument, eINVAL :: ErrorCode
-invalidSeek, eSPIPE :: ErrorCode
-isADirectory, eISDIR :: ErrorCode
-noChildProcess, eCHILD :: ErrorCode
-noLocksAvailable, eNOLCK :: ErrorCode
-noSpaceLeftOnDevice, eNOSPC :: ErrorCode
-noSuchOperationOnDevice, eNODEV :: ErrorCode
-noSuchDeviceOrAddress, eNXIO :: ErrorCode
-noSuchFileOrDirectory, eNOENT :: ErrorCode
-noSuchProcess, eSRCH :: ErrorCode
-notADirectory, eNOTDIR :: ErrorCode
-notEnoughMemory, eNOMEM :: ErrorCode
-operationNotImplemented, eNOSYS :: ErrorCode
-operationNotPermitted, ePERM :: ErrorCode
-permissionDenied, eACCES :: ErrorCode
-readOnlyFileSystem, eROFS :: ErrorCode
-resourceBusy, eBUSY :: ErrorCode
-resourceDeadlockAvoided, eDEADLK :: ErrorCode
-resourceTemporarilyUnavailable, eAGAIN :: ErrorCode
-tooManyLinks, eMLINK :: ErrorCode
-tooManyOpenFiles, eMFILE :: ErrorCode
-tooManyOpenFilesInSystem, eNFILE :: ErrorCode
-</ProgramListing>
-
-</Para>
-
-</Sect2>
-
-</Sect1>
<!ENTITY glaexts SYSTEM "glasgow_exts.sgml" >
<!ENTITY parallel SYSTEM "parallel.sgml" >
<!ENTITY vs-hs SYSTEM "vs_haskell.sgml" >
- <!ENTITY libs SYSTEM "libraries.sgml" >
- <!ENTITY posix SYSTEM "posix.sgml" >
- <!ENTITY libmisc SYSTEM "libmisc.sgml" >
<!ENTITY wrong SYSTEM "gone_wrong.sgml" >
+ <!ENTITY libraries SYSTEM "libraries.sgml" >
<!ENTITY utils SYSTEM "utils.sgml" >
- <!ENTITY mutablearray SYSTEM "MutableArray.sgml">
- <!ENTITY bytearray SYSTEM "ByteArray.sgml">
<!ENTITY win32-dll SYSTEM "win32-dlls.sgml">
]>
<Book>
&prof
&sooner
&lang
-&libs
&wrong
+&libraries
&utils
&win32-dll
projects / ghc-hetmet.git / commitdiff