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

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

6 files changed, 182 insertions, 11 deletions

diff --git a/System/Posix/Directory.hsc b/System/Posix/Directory.hsc
index 490953c..3139e98 100644
--- a/System/Posix/Directory.hsc
+++ b/System/Posix/Directory.hsc
@@ -40,6 +40,9 @@ import System.Directory hiding (createDirectory)
 import Foreign
 import Foreign.C
 
+-- | @createDirectory dir mode@ calls @mkdir@ to 
+--   create a new directory, @dir@, with permissions based on
+--  @mode@.
 createDirectory :: FilePath -> FileMode -> IO ()
 createDirectory name mode =
   withCString name $ \s -> 
@@ -50,12 +53,18 @@ foreign import ccall unsafe "mkdir"
 
 newtype DirStream = DirStream (Ptr CDir)
 
+-- | @openDirStream dir@ calls @opendir@ to obtain a
+--   directory stream for @dir@.
 openDirStream :: FilePath -> IO DirStream
 openDirStream name =
   withCString name $ \s -> do
     dirp <- throwErrnoPathIfNull "openDirStream" name $ c_opendir s
     return (DirStream dirp)
 
+-- | @readDirStream dp@ calls @readdir@ to obtain the
+--   next directory entry (@struct dirent@) for the open directory
+--   stream @dp@, and returns the @d_name@ member of that
+--  structure.
 readDirStream :: DirStream -> IO FilePath
 readDirStream (DirStream dirp) =
   alloca $ \ptr_dEnt  -> loop ptr_dEnt
@@ -78,9 +87,13 @@ readDirStream (DirStream dirp) =
 		    then return []
 		    else throwErrno "readDirStream"
 
+-- | @rewindDirStream dp@ calls @rewinddir@ to reposition
+--   the directory stream @dp@ at the beginning of the directory.
 rewindDirStream :: DirStream -> IO ()
 rewindDirStream (DirStream dirp) = c_rewinddir dirp
 
+-- | @closeDirStream dp@ calls @closedir@ to close
+--   the directory stream @dp@.
 closeDirStream :: DirStream -> IO ()
 closeDirStream (DirStream dirp) = do
   throwErrnoIfMinus1_ "closeDirStream" (c_closedir dirp)
@@ -107,9 +120,14 @@ foreign import ccall unsafe "telldir"
  kept around for b.wards compatibility and for having more POSIXy
  names
 -}
+
+-- | @getWorkingDirectory@ calls @getcwd@ to obtain the name
+--   of the current working directory.
 getWorkingDirectory :: IO FilePath
 getWorkingDirectory = getCurrentDirectory
 
+-- | @changeWorkingDirectory dir@ calls @chdir@ to change
+--   the current working directory to @dir@.
 changeWorkingDirectory :: FilePath -> IO ()
 changeWorkingDirectory name = setCurrentDirectory name
 
diff --git a/System/Posix/Files.hsc b/System/Posix/Files.hsc
index 3bdfe98..0930563 100644
--- a/System/Posix/Files.hsc
+++ b/System/Posix/Files.hsc
@@ -170,6 +170,8 @@ symbolicLinkMode = (#const S_IFLNK)
 socketMode :: FileMode
 socketMode = (#const S_IFSOCK)
 
+-- | @setFileMode path mode@ calls @chmod@ to set the
+--   permission bits associated with file @path@ to @mode@.
 setFileMode :: FilePath -> FileMode -> IO ()
 setFileMode name m =
   withCString name $ \s -> do
@@ -182,6 +184,9 @@ setFdMode fd m =
 foreign import ccall unsafe "fchmod" 
   c_fchmod :: Fd -> CMode -> IO CInt
 
+-- | @setFileCreationMask mode@ calls @umask@ to set
+--   the process's file creation mask to @mode@.  The previous file
+--   creation mask is returned.
 setFileCreationMask :: FileMode -> IO FileMode
 setFileCreationMask mask = c_umask mask
 
@@ -281,6 +286,8 @@ isSymbolicLink stat =
 isSocket stat = 
   (fileMode stat `intersectFileModes` fileTypeModes) == socketMode
 
+-- | @getFileStatus path@ calls @stat@ to get the
+--   @FileStatus@ information for the file @path@.
 getFileStatus :: FilePath -> IO FileStatus
 getFileStatus path = do
   fp <- mallocForeignPtrBytes (#const sizeof(struct stat)) 
@@ -289,6 +296,9 @@ getFileStatus path = do
       throwErrnoPathIfMinus1_ "getFileStatus" path (c_stat s p)
   return (FileStatus fp)
 
+-- | @getFdStatus fd@ calls @fstat@ to get the
+--   @FileStatus@ information for the file associated with
+--   @Fd@ @fd@.
 getFdStatus :: Fd -> IO FileStatus
 getFdStatus (Fd fd) = do
   fp <- mallocForeignPtrBytes (#const sizeof(struct stat)) 
@@ -307,6 +317,9 @@ getSymbolicLinkStatus path = do
 foreign import ccall unsafe "lstat" 
   c_lstat :: CString -> Ptr CStat -> IO CInt
 
+-- | @createNamedPipe fifo mode@ calls @mkfifo@ to 
+--   create a new named pipe, @fifo@, with permissions based on
+--   @mode@.
 createNamedPipe :: FilePath -> FileMode -> IO ()
 createNamedPipe name mode = do
   withCString name $ \s -> 
@@ -323,12 +336,16 @@ foreign import ccall unsafe "mknod"
 -- -----------------------------------------------------------------------------
 -- Hard links
 
+-- | @createLink old new@ calls @link@ to create a 
+--   new path, @new@, linked to an existing file, @old@.
 createLink :: FilePath -> FilePath -> IO ()
 createLink name1 name2 =
   withCString name1 $ \s1 ->
   withCString name2 $ \s2 ->
   throwErrnoPathIfMinus1_ "createLink" name1 (c_link s1 s2)
 
+-- | @removeLink path@ calls @unlink@ to remove the link
+--   named @path@.
 removeLink :: FilePath -> IO ()
 removeLink name =
   withCString name $ \s ->
@@ -369,6 +386,8 @@ foreign import ccall unsafe "readlink"
 -- -----------------------------------------------------------------------------
 -- Renaming files
 
+-- | @rename old new@ calls @rename@ to rename a 
+--   file or directory from @old@ to @new@.
 rename :: FilePath -> FilePath -> IO ()
 rename name1 name2 =
   withCString name1 $ \s1 ->
@@ -378,6 +397,9 @@ rename name1 name2 =
 -- -----------------------------------------------------------------------------
 -- chmod()
 
+-- | @setOwnerAndGroup path uid gid@ calls @chown@ to
+--   set the @UserID@ and @GroupID@ associated with file
+--   @path@ to @uid@ and @gid@, respectively.
 setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
 setOwnerAndGroup name uid gid = do
   withCString name $ \s ->
@@ -407,6 +429,9 @@ foreign import ccall unsafe "lchown"
 -- -----------------------------------------------------------------------------
 -- utime()
 
+-- | @setFileTimes path atime mtime@ calls @utime@ to
+--   set the access and modification times associated with file
+--   @path@ to @atime@ and @mtime@, respectively.
 setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
 setFileTimes name atime mtime = do
   withCString name $ \s ->
@@ -415,6 +440,9 @@ setFileTimes name atime mtime = do
      (#poke struct utimbuf, modtime) p mtime
      throwErrnoPathIfMinus1_ "setFileTimes" name (c_utime s p)
 
+-- | @touchFile path@ calls @utime@ to
+--   set the access and modification times associated with file
+--   @path@ to the current time.
 touchFile :: FilePath -> IO ()
 touchFile name = do
   withCString name $ \s ->
@@ -502,6 +530,13 @@ pathVarConst v = case v of
 	SymbolicLinkLimit	-> error "_PC_SYMLINK_MAX not available"
 #endif
 
+
+-- | @getPathVar var path@ calls @pathconf@ to obtain the
+--   dynamic value of the requested configurable file limit or option associated
+--   with file or directory @path@.  For
+--   defined file limits, @getPathVar@ returns the associated
+--   value.  For defined file options, the result of @getPathVar@
+--   is undefined, but not failure.
 getPathVar :: FilePath -> PathVar -> IO Limit
 getPathVar name v = do
   withCString name $ \ nameP -> 
@@ -511,6 +546,13 @@ getPathVar name v = do
 foreign import ccall unsafe "pathconf" 
   c_pathconf :: CString -> CInt -> IO CLong
 
+
+-- | @getFdPathVar var fd@ calls @fpathconf@ to obtain the
+--   dynamic value of the requested configurable file limit or option associated
+--   with the file or directory attached to the open channel @fd@.
+--   For defined file limits, @getFdPathVar@ returns the associated
+--   value.  For defined file options, the result of @getFdPathVar@
+--   is undefined, but not failure.
 getFdPathVar :: Fd -> PathVar -> IO Limit
 getFdPathVar fd v =
     throwErrnoIfMinus1 "getFdPathVar" $ 
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
diff --git a/System/Posix/Terminal.hsc b/System/Posix/Terminal.hsc
index 5e4a017..9fb614d 100644
--- a/System/Posix/Terminal.hsc
+++ b/System/Posix/Terminal.hsc
@@ -357,7 +357,8 @@ withOutputSpeed termios br = unsafePerformIO $ do
 foreign import ccall unsafe "cfsetospeed"
   c_cfsetospeed :: Ptr CTermios -> CSpeed -> IO CInt
 
-
+-- | @getTerminalAttributes fd@ calls @tcgetattr@ to obtain
+--   the @TerminalAttributes@ associated with @Fd@ @fd@.
 getTerminalAttributes :: Fd -> IO TerminalAttributes
 getTerminalAttributes fd = do
   fp <- mallocForeignPtrBytes (#const sizeof(struct termios))
@@ -373,6 +374,9 @@ data TerminalState
   | WhenDrained
   | WhenFlushed
 
+-- | @setTerminalAttributes fd attr ts@ calls @tcsetattr@ to change
+--   the @TerminalAttributes@ associated with @Fd@ @fd@ to
+--   @attr@, when the terminal is in the state indicated by @ts@.
 setTerminalAttributes :: Fd
                       -> TerminalAttributes
                       -> TerminalState
@@ -390,7 +394,9 @@ setTerminalAttributes fd termios state = do
 foreign import ccall unsafe "tcsetattr"
    c_tcsetattr :: Fd -> CInt -> Ptr CTermios -> IO CInt
 
-
+-- | @sendBreak fd duration@ calls @tcsendbreak@ to transmit a
+--   continuous stream of zero-valued bits on @Fd@ @fd@ for the
+--   specified implementation-dependent @duration@.
 sendBreak :: Fd -> Int -> IO ()
 sendBreak fd duration
   = throwErrnoIfMinus1_ "sendBreak" (c_tcsendbreak fd (fromIntegral duration))
@@ -398,6 +404,8 @@ sendBreak fd duration
 foreign import ccall unsafe "tcsendbreak"
   c_tcsendbreak :: Fd -> CInt -> IO CInt
 
+-- | @drainOutput fd@ calls @tcdrain@ to block until all output
+--   written to @Fd@ @fd@ has been transmitted.
 drainOutput :: Fd -> IO ()
 drainOutput fd = throwErrnoIfMinus1_ "drainOutput" (c_tcdrain fd)
 
@@ -410,6 +418,9 @@ data QueueSelector
   | OutputQueue		-- TCOFLUSH
   | BothQueues		-- TCIOFLUSH
 
+-- | @discardData fd queues@ calls @tcflush@ to discard
+--   pending input and\/or output for @Fd@ @fd@,
+--   as indicated by the @QueueSelector@ @queues@.
 discardData :: Fd -> QueueSelector -> IO ()
 discardData fd queue =
   throwErrnoIfMinus1_ "discardData" (c_tcflush fd (queue2Int queue))
@@ -423,11 +434,14 @@ foreign import ccall unsafe "tcflush"
   c_tcflush :: Fd -> CInt -> IO CInt
 
 data FlowAction
-  = SuspendOutput	-- TCOOFF
-  | RestartOutput	-- TCOON
-  | TransmitStop	-- TCIOFF
-  | TransmitStart	-- TCION
-
+  = SuspendOutput	-- ^ TCOOFF
+  | RestartOutput	-- ^ TCOON
+  | TransmitStop	-- ^ TCIOFF
+  | TransmitStart	-- ^ TCION
+
+-- | @controlFlow fd action@ calls @tcflow@ to control the 
+--   flow of data on @Fd@ @fd@, as indicated by
+--   @action@.
 controlFlow :: Fd -> FlowAction -> IO ()
 controlFlow fd action =
   throwErrnoIfMinus1_ "controlFlow" (c_tcflow fd (action2Int action))
@@ -441,6 +455,9 @@ controlFlow fd action =
 foreign import ccall unsafe "tcflow"
   c_tcflow :: Fd -> CInt -> IO CInt
 
+-- | @getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
+--   obtain the @ProcessGroupID@ of the foreground process group 
+--   associated with the terminal attached to @Fd@ @fd@.
 getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
 getTerminalProcessGroupID fd = do
   throwErrnoIfMinus1 "getTerminalProcessGroupID" (c_tcgetpgrp fd)
@@ -448,6 +465,10 @@ getTerminalProcessGroupID fd = do
 foreign import ccall unsafe "tcgetpgrp"
   c_tcgetpgrp :: Fd -> IO CPid
 
+-- | @setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
+--   set the @ProcessGroupID@ of the foreground process group 
+--   associated with the terminal attached to @Fd@ 
+--   @fd@ to @pgid@.
 setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
 setTerminalProcessGroupID fd pgid =
   throwErrnoIfMinus1_ "setTerminalProcessGroupID" (c_tcsetpgrp fd pgid)
@@ -458,6 +479,8 @@ foreign import ccall unsafe "tcsetpgrp"
 -- -----------------------------------------------------------------------------
 -- file descriptor queries
 
+-- | @queryTerminal fd@ calls @isatty@ to determine whether or
+--   not @Fd@ @fd@ is associated with a terminal.
 queryTerminal :: Fd -> IO Bool
 queryTerminal fd = do
   r <- c_isatty fd
@@ -467,7 +490,10 @@ queryTerminal fd = do
 foreign import ccall unsafe "isatty"
   c_isatty :: Fd -> IO CInt
 
-
+-- | @getTerminalName fd@ calls @ttyname@ to obtain a name associated
+--   with the terminal for @Fd@ @fd@. If @fd@ is associated
+--   with a terminal, @getTerminalName@ returns the name of the
+--   terminal.
 getTerminalName :: Fd -> IO FilePath
 getTerminalName fd = do
   s <- throwErrnoIfNull "getTerminalName" (c_ttyname fd)
@@ -476,6 +502,11 @@ getTerminalName fd = do
 foreign import ccall unsafe "ttyname"
   c_ttyname :: Fd -> IO CString
 
+-- | @getControllingTerminalName@ calls @ctermid@ to obtain
+--   a name associated with the controlling terminal for the process.  If a
+--   controlling terminal exists,
+--   @getControllingTerminalName@ returns the name of the
+--   controlling terminal.
 getControllingTerminalName :: IO FilePath
 getControllingTerminalName = do
   s <- throwErrnoIfNull "getControllingTerminalName" (c_ctermid nullPtr)
diff --git a/System/Posix/Time.hsc b/System/Posix/Time.hsc
index a1d8f2f..d877f91 100644
--- a/System/Posix/Time.hsc
+++ b/System/Posix/Time.hsc
@@ -28,6 +28,8 @@ import Foreign.C
 -- -----------------------------------------------------------------------------
 -- epochTime
 
+-- | @epochTime@ calls @time@ to obtain the number of 
+--   seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
 epochTime :: IO EpochTime
 epochTime = throwErrnoIfMinus1 "epochTime" (c_time nullPtr)
 
diff --git a/System/Posix/User.hsc b/System/Posix/User.hsc
index 69976a1..ecd57e5 100644
--- a/System/Posix/User.hsc
+++ b/System/Posix/User.hsc
@@ -54,30 +54,40 @@ import Control.Concurrent.MVar  ( newMVar, withMVar )
 -- -----------------------------------------------------------------------------
 -- user environemnt
 
+-- | @getRealUserID@ calls @getuid@ to obtain the real @UserID@
+--   associated with the current process.
 getRealUserID :: IO UserID
 getRealUserID = c_getuid
 
 foreign import ccall unsafe "getuid"
   c_getuid :: IO CUid
 
+-- | @getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
+--   associated with the current process.
 getRealGroupID :: IO GroupID
 getRealGroupID = c_getgid
 
 foreign import ccall unsafe "getgid"
   c_getgid :: IO CGid
 
+-- | @getEffectiveUserID@ calls @geteuid@ to obtain the effective
+--   @UserID@ associated with the current process.
 getEffectiveUserID :: IO UserID
 getEffectiveUserID = c_geteuid
 
 foreign import ccall unsafe "geteuid"
   c_geteuid :: IO CUid
 
+-- | @getEffectiveGroupID@ calls @getegid@ to obtain the effective
+--   @GroupID@ associated with the current process.
 getEffectiveGroupID :: IO GroupID
 getEffectiveGroupID = c_getegid
 
 foreign import ccall unsafe "getegid"
   c_getegid :: IO CGid
 
+-- | @getGroups@ calls @getgroups@ to obtain the list of
+--   supplementary @GroupID@s associated with the current process.
 getGroups :: IO [GroupID]
 getGroups = do
     ngroups <- c_getgroups 0 nullPtr
@@ -89,21 +99,30 @@ getGroups = do
 foreign import ccall unsafe "getgroups"
   c_getgroups :: CInt -> Ptr CGid -> IO CInt
 
--- ToDo: use getlogin_r
+
+
+
+-- | @getLoginName@ calls @getlogin@ to obtain the login name
+--   associated with the current process.
 getLoginName :: IO String
 getLoginName =  do
+    -- ToDo: use getlogin_r
     str <- throwErrnoIfNull "getLoginName" c_getlogin
     peekCString str
 
 foreign import ccall unsafe "getlogin"
   c_getlogin :: IO CString
 
+-- | @setUserID uid@ calls @setuid@ to set the real, effective, and
+--   saved set-user-id associated with the current process to @uid@.
 setUserID :: UserID -> IO ()
 setUserID uid = throwErrnoIfMinus1_ "setUserID" (c_setuid uid)
 
 foreign import ccall unsafe "setuid"
   c_setuid :: CUid -> IO CInt
 
+-- | @setGroupID gid@ calls @setgid@ to set the real, effective, and
+--   saved set-group-id associated with the current process to @gid@.
 setGroupID :: GroupID -> IO ()
 setGroupID gid = throwErrnoIfMinus1_ "setGroupID" (c_setgid gid)
 
@@ -113,6 +132,8 @@ foreign import ccall unsafe "setgid"
 -- -----------------------------------------------------------------------------
 -- User names
 
+-- | @getEffectiveUserName@ gets the name
+--   associated with the effective @UserID@ of the process.
 getEffectiveUserName :: IO String
 getEffectiveUserName = do
     euid <- getEffectiveUserID
@@ -129,6 +150,9 @@ data GroupEntry =
   groupMembers :: [String]
  }
 
+-- | @getGroupEntryForID gid@ calls @getgrgid@ to obtain
+--   the @GroupEntry@ information associated with @GroupID@
+--   @gid@.
 getGroupEntryForID :: GroupID -> IO GroupEntry
 #ifdef HAVE_GETGRGID_R
 getGroupEntryForID gid = do
@@ -149,7 +173,9 @@ foreign import ccall unsafe "getgrgid_r"
 getGroupEntryForID = error "System.Posix.User.getGroupEntryForID: not supported"
 #endif
 
-
+-- | @getGroupEntryForName name@ calls @getgrnam@ to obtain
+--   the @GroupEntry@ information associated with the group called
+--   @name@.
 getGroupEntryForName :: String -> IO GroupEntry
 #ifdef HAVE_GETGRNAM_R
 getGroupEntryForName name = do
@@ -210,6 +236,9 @@ lock = unsafePerformIO $ newMVar ()
 {-# NOINLINE lock #-}
 #endif
 
+-- | @getUserEntryForID gid@ calls @getpwuid@ to obtain
+--   the @UserEntry@ information associated with @UserID@
+--   @uid@.
 getUserEntryForID :: UserID -> IO UserEntry
 #ifdef HAVE_GETPWUID_R
 getUserEntryForID uid = do
@@ -237,6 +266,9 @@ foreign import ccall unsafe "getpwuid"
 getUserEntryForID = error "System.Posix.User.getUserEntryForID: not supported"
 #endif
 
+-- | @getUserEntryForName name@ calls @getpwnam@ to obtain
+--   the @UserEntry@ information associated with the user login
+--   @name@.
 getUserEntryForName :: String -> IO UserEntry
 #if HAVE_GETPWNAM_R
 getUserEntryForName name = do