[project @ 2005-11-10 12:58:32 by simonmar]

Some docs for System.Posix, from Bj?rn Bringert

1 files changed, 47 insertions, 1 deletions

diff --git a/System/Posix/Process.hsc b/System/Posix/Process.hsc
index 9551040..8a66a8f 100644
--- a/System/Posix/Process.hsc
+++ b/System/Posix/Process.hsc
@@ -90,33 +90,46 @@ import GHC.TopHandler	( runIO )
 -- -----------------------------------------------------------------------------
 -- Process environment
 
+-- | <function>getProcessID</function> calls <function>getpid</function> to obtain 
+--   the <literal>ProcessID</literal> for
+--   the current process.
 getProcessID :: IO ProcessID
 getProcessID = c_getpid
 
 foreign import ccall unsafe "getpid"
    c_getpid :: IO CPid
 
+-- | <function>getProcessID</function> calls <function>getppid</function> to obtain the <literal>ProcessID</literal> for
+--   the parent of the current process.
 getParentProcessID :: IO ProcessID
 getParentProcessID = c_getppid
 
 foreign import ccall unsafe "getppid"
   c_getppid :: IO CPid
 
+-- | <function>getProcessGroupID</function> calls <function>getpgrp</function> to obtain the
+--   <literal>ProcessGroupID</literal> for the current process.
 getProcessGroupID :: IO ProcessGroupID
 getProcessGroupID = c_getpgrp
 
 foreign import ccall unsafe "getpgrp"
   c_getpgrp :: IO CPid
 
+-- | <literal>createProcessGroup pid</literal> calls <function>setpgid</function> to make
+--   process <literal>pid</literal> a new process group leader.
 createProcessGroup :: ProcessID -> IO ProcessGroupID
 createProcessGroup pid = do
   throwErrnoIfMinus1_ "createProcessGroup" (c_setpgid pid 0)
   return pid
 
+-- | <literal>joinProcessGroup pgid</literal> calls <function>setpgid</function> to set the
+--   <literal>ProcessGroupID</literal> of the current process to <literal>pgid</literal>.
 joinProcessGroup :: ProcessGroupID -> IO ()
 joinProcessGroup pgid =
   throwErrnoIfMinus1_ "joinProcessGroup" (c_setpgid 0 pgid)
 
+-- | <literal>setProcessGroupID pid pgid</literal> calls <function>setpgid</function> to set the
+--   <literal>ProcessGroupID</literal> for process <literal>pid</literal> to <literal>pgid</literal>.
 setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
 setProcessGroupID pid pgid =
   throwErrnoIfMinus1_ "setProcessGroupID" (c_setpgid pid pgid)
@@ -124,6 +137,8 @@ setProcessGroupID pid pgid =
 foreign import ccall unsafe "setpgid"
   c_setpgid :: CPid -> CPid -> IO CInt
 
+-- | <function>createSession</function> calls <function>setsid</function> to create a new session
+--   with the current process as session leader.
 createSession :: IO ProcessGroupID
 createSession = throwErrnoIfMinus1 "createSession" c_setsid
 
@@ -143,6 +158,8 @@ data ProcessTimes
 		 , childSystemTime :: ClockTick
 		 }
 
+-- | <function>getProcessTimes</function> calls <function>times</function> to obtain time-accounting
+--   information for the current process and its children.
 getProcessTimes :: IO ProcessTimes
 getProcessTimes = do
    allocaBytes (#const sizeof(struct tms)) $ \p_tms -> do
@@ -239,6 +256,14 @@ forkProcess action = do
 foreign import ccall "forkProcess" forkProcessPrim :: StablePtr (IO ()) -> IO CPid
 #endif /* __GLASGOW_HASKELL__ */
 
+-- | <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>.
 executeFile :: FilePath			    -- Command
             -> Bool			    -- Search PATH?
             -> [String]			    -- Arguments
@@ -284,6 +309,12 @@ data ProcessStatus = Exited ExitCode
                    | Stopped Signal
 		   deriving (Eq, Ord, Show)
 
+-- | <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.
 getProcessStatus :: Bool -> Bool -> ProcessID -> IO (Maybe ProcessStatus)
 getProcessStatus block stopped pid =
   alloca $ \wstatp -> do
@@ -298,6 +329,13 @@ getProcessStatus block stopped pid =
 foreign import ccall safe "waitpid"
   c_waitpid :: CPid -> Ptr CInt -> CInt -> IO CPid
 
+-- | <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.
 getGroupProcessStatus :: Bool
                       -> Bool
                       -> ProcessGroupID
@@ -310,7 +348,12 @@ getGroupProcessStatus block stopped pgid =
       0  -> return Nothing
       _  -> do ps <- decipherWaitStatus wstatp
 	       return (Just (pid, ps))
-
+-- | <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.
 getAnyProcessStatus :: Bool -> Bool -> IO (Maybe (ProcessID, ProcessStatus))
 getAnyProcessStatus block stopped = getGroupProcessStatus block stopped 1
 
@@ -367,6 +410,9 @@ foreign import ccall unsafe "__hsunix_wstopsig"
 -- -----------------------------------------------------------------------------
 -- Exiting
 
+-- | <literal>exitImmediately status</literal> calls <function>&lowbar;exit</function> to terminate the process
+--   with the indicated exit <literal>status</literal>.
+--   The operation never returns.
 exitImmediately :: ExitCode -> IO ()
 exitImmediately exitcode = c_exit (exitcode2Int exitcode)
   where