[project @ 1999-07-14 11:33:10 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / posix.vsgml

diff --git a/ghc/docs/users_guide/posix.vsgml b/ghc/docs/users_guide/posix.vsgml
index 9896fd1..44eb171 100644 (file)
--- a/ghc/docs/users_guide/posix.vsgml
+++ b/ghc/docs/users_guide/posix.vsgml
@@ -291,8 +291,19 @@ 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.
 
+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' @fork()@ semantics. Using
+Haskell, there's the extra complication that arguments to
+@executeFile@ might come from files that are read lazily (using
+@hGetContents@, or some such.) If this is the case, then for your own
+sanity, please ensure that the arguments to @executeFile@ have been
+fully evaluated before calling @forkProcess@ (followed by
+@executeFile@.) Consider yourself warned :-)
+
 A successful @executeFile@ overlays the current process image with 
 a new one, so it only returns on failure.
+
 <tscreen><verb>
 runProcess :: FilePath                    -- Command
            -> [String]                    -- Arguments
@@ -493,15 +504,18 @@ installHandler :: Signal
                -> IO Handler            -- old handler
 </verb></tscreen>
 
-@installHandler int handler iset@ calls @sigaction@ to install
-an interrupt handler for signal @int@.  If @handler@ is
-@Default@, @SIG_DFL@ is installed; if @handler@ is
-@Ignore@, @SIG_IGN@ is installed; if @handler@ is
-@Catch action@, a handler is installed which will invoke @action@ as a
-replacement for @main@.  If @iset@ is @Just s@, then the
-@sa_mask@ of the @sigaction@ structure is set to @s@;
-otherwise it is cleared.  The previously installed signal handler for
-@int@ is returned.
+@installHandler int handler iset@ calls @sigaction@ to install an
+interrupt handler for signal @int@.  If @handler@ is @Default@,
+@SIG_DFL@ is installed; if @handler@ is @Ignore@, @SIG_IGN@ is
+installed; if @handler@ is @Catch action@, a handler is installed
+which will invoke @action@ in a new thread when (or shortly after) the
+signal is received.  See Section <ref name="Concurrent Haskell"
+id="concurrent-haskell"> for details on how to communicate between
+threads.
+
+If @iset@ is @Just s@, then the @sa_mask@ of the @sigaction@ structure
+is set to @s@; otherwise it is cleared.  The previously installed
+signal handler for @int@ is returned.
 
 <tscreen><verb>
 getSignalMask :: IO SignalSet
@@ -546,10 +560,12 @@ awaitSignal :: Maybe SignalSet -> IO ()
 </verb></tscreen>
 
 @awaitSignal iset@ suspends execution until an interrupt is received.
-If @iset@ is @Just s@, @awaitSignal@ calls 
-@sigsuspend@, installing @s@ as the new signal mask before
-suspending execution; otherwise, it calls @pause@.  If successful,
-@awaitSignal@ does not return.
+If @iset@ is @Just s@, @awaitSignal@ calls @sigsuspend@, installing
+@s@ as the new signal mask before suspending execution; otherwise, it
+calls @pause@.  @awaitSignal@ returns on receipt of a signal.  If you
+have installed any signal handlers with @installHandler@, it may be
+wise to call @yield@ directly after @awaitSignal@ to ensure that the
+signal handler runs as promptly.
 
 <tscreen><verb>
 scheduleAlarm :: Int -> IO Int
@@ -1078,7 +1094,7 @@ Various other causes.
 </descrip>
 
 <sect2>Posix Input and Output Primitives
-<label id="Inut Output">
+<label id="Input/Output">
 <p>
 <nidx>Posix, input/output</nidx>
 
@@ -1087,7 +1103,7 @@ createPipe :: IO (Fd, Fd)
 </verb></tscreen>
 
 @createPipe@ calls @pipe@ to create a pipe and returns a pair of
-@Fd@s, the first for writing and the second for reading.
+@Fd@s, the first for reading and the second for writing.
 
 <tscreen><verb>
 dup :: Fd -> IO Fd