path: root/ghc/docs/users_guide/posix.vsgml

%************************************************************************
%*                                                                      *
<sect1>The Posix library
<label id="Posix-library">
<p>
<nidx>Posix library</nidx>
<nidx>libraries, Posix</nidx>
%*                                                                      *
%************************************************************************

The @Posix@ interface gives you access to the set of OS services
standardised by POSIX 1003.1b (or the <em>IEEE Portable Operating System
Interface for Computing Environments</em> - IEEE Std. 1003.1). The
interface is accessed by @import Posix@ and adding 
@-syslib posix@ on your command-line.

<sect2>Posix data types
<label id="Posix data types">
<p>
<nidx>Posix, data types</nidx>


<tscreen><verb>
data ByteCount  -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @ByteCount@ is a primitive of type @unsigned@. At a minimum,
an conforming implementation must support values in the range
@[0, UINT_MAX]@.

<tscreen><verb>
data ClockTick  -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @ClockTick@ is a primitive of type @clock_t@, which
is used to measure intervals of time in fractions of a second.  The 
resolution is determined by @getSysVar ClockTick@.

<tscreen><verb>
data DeviceID  -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @DeviceID@ is a primitive of type @dev_t@.  It must
be an arithmetic type.

<tscreen><verb>
data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @EpochTime@ is a primitive of type @time_t@, which is
used to measure seconds since the Epoch.  At a minimum, the implementation 
must support values in the range @[0, INT_MAX]@.

<tscreen><verb>
data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @FileID@ is a primitive of type @ino_t@.  It must
be an arithmetic type.

<tscreen><verb>
data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @FileMode@ is a primitive of type @mode_t@.
It must be an arithmetic type.

<tscreen><verb>
data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @FileOffset@ is a primitive of type @off_t@.  It must
be an arithmetic type.

<tscreen><verb>
data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @GroupID@ is a primitive of type @gid_t@.  It must
be an arithmetic type.
<tscreen><verb>
data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @Limit@ is a primitive of type @long@.
At a minimum, the implementation must support values in the range 
@[LONG_MIN, LONG_MAX]@.

<tscreen><verb>
data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @LinkCount@ is a primitive of type @nlink_t@.  It must
be an arithmetic type.

<tscreen><verb>
data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
type ProcessGroupID = ProcessID
</verb></tscreen>

A @ProcessID@ is a primitive of type @pid_t@.  It
must be a signed arithmetic type.
<tscreen><verb>
data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
</verb></tscreen>

A @UserID@ is a primitive of type @uid_t@.  It
must be an arithmetic type.

<tscreen><verb>
data DirStream
</verb></tscreen>
A @DirStream@ is a primitive of type @DIR *@.

<tscreen><verb>
data FileStatus
</verb></tscreen>
A @FileStatus@ is a primitive of type @struct stat@.

<tscreen><verb>
data GroupEntry
</verb></tscreen>

A @GroupEntry@ is a primitive of type @struct group@.
<tscreen><verb>
data ProcessTimes
</verb></tscreen>

@ProcessTimes@ is a primitive structure containing a
@clock_t@ and a @struct tms@.

<tscreen><verb>
data SignalSet
</verb></tscreen>

An @SignalSet@ is a primitive of type @sigset_t@.

<tscreen><verb>
data SystemID
</verb></tscreen>

A @SystemID@ is a primitive of type @struct utsname@.

<tscreen><verb>
data TerminalAttributes
</verb></tscreen>
@TerminalAttributes@ is a primitive of type @struct termios@.

<tscreen><verb>
data UserEntry
</verb></tscreen>

A @UserEntry@ is a primitive of type @struct passwd@.

<tscreen><verb>
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)
</verb></tscreen>

<sect2>Posix Process Primitives
<label id="Process Primitives">
<p>

<tscreen><verb>
forkProcess :: IO (Maybe ProcessID)
</verb></tscreen>

@forkProcess@ calls @fork@, returning
@Just pid@ to the parent, where @pid@ is the
ProcessID of the child, and returning @Nothing@ to the
child.

<tscreen><verb>
executeFile :: FilePath                   -- Command
            -> Bool                       -- Search PATH?
            -> [String]                   -- Arguments
            -> Maybe [(String, String)]   -- Environment
            -> IO ()
</verb></tscreen>

@executeFile cmd args env@ calls one of the
@execv*@ 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 @execv*@ as @arg[0]@;
the argument list passed to @executeFile@ therefore begins 
with @arg[1]@.

<tscreen><verb>
Search PATH?    Supersede environ?      Call
~~~~~~~~~~~~    ~~~~~~~~~~~~~~~~~~      ~~~~~~~
False           False                   execv
False           True                    execve
True            False                   execvp
True            True                    execvpe*
</verb></tscreen>

Note that @execvpe@ 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.

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
           -> 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 ()
</verb></tscreen>

@runProcess@ is our candidate for the high-level OS-independent
primitive.

@runProcess cmd args env wd inhdl outhdl errhdl@ runs @cmd@
(searching the current @PATH@) with arguments @args@.  If
@env@ is @Just pairs@, the command is executed with the
environment specified by @pairs@ of variables and values;
otherwise, the command is executed with the current environment.  If
@wd@ is @Just dir@, the command is executed with working
directory @dir@; otherwise, the command is executed in the current
working directory.  If @{in,out,err@hdl} is @Just handle@, the
command is executed with the @Fd@ for @std{in,out,err@}
attached to the specified @handle@; otherwise, the @Fd@ for
@std{in,out,err@} is left unchanged.

<tscreen><verb>
getProcessStatus :: Bool              -- Block?
                 -> Bool              -- Stopped processes?
                 -> ProcessID 
                 -> IO (Maybe ProcessStatus)
</verb></tscreen>

@getProcessStatus blk stopped pid@ calls @waitpid@, returning
@Just tc@, the @ProcessStatus@ for process @pid@ if it is
available, @Nothing@ otherwise.  If @blk@ is @False@, then
@WNOHANG@ is set in the options for @waitpid@, otherwise not.
If @stopped@ is @True@, then @WUNTRACED@ is set in the
options for @waitpid@, otherwise not.

<tscreen><verb>
getGroupProcessStatus :: Bool         -- Block?
                      -> Bool         -- Stopped processes?
                      -> ProcessGroupID 
                      -> IO (Maybe (ProcessID, ProcessStatus))
</verb></tscreen>

@getGroupProcessStatus blk stopped pgid@ calls @waitpid@,
returning @Just (pid, tc)@, the @ProcessID@ and
@ProcessStatus@ for any process in group @pgid@ if one is
available, @Nothing@ otherwise.  If @blk@ is @False@, then
@WNOHANG@ is set in the options for @waitpid@, otherwise not.
If @stopped@ is @True@, then @WUNTRACED@ is set in the
options for @waitpid@, otherwise not.

<tscreen><verb>
getAnyProcessStatus :: Bool           -- Block?
                    -> Bool           -- Stopped processes?
                    -> IO (Maybe (ProcessID, ProcessStatus))
</verb></tscreen>

@getAnyProcessStatus blk stopped@ calls @waitpid@, returning
@Just (pid, tc)@, the @ProcessID@ and @ProcessStatus@ for any
child process if one is available, @Nothing@ otherwise.  If
@blk@ is @False@, then @WNOHANG@ is set in the options for
@waitpid@, otherwise not.  If @stopped@ is @True@, then
@WUNTRACED@ is set in the options for @waitpid@, otherwise not.

<tscreen><verb>
exitImmediately :: ExitCode -> IO ()
</verb></tscreen>

@exitImmediately status@ calls @_exit@ to terminate the process
with the indicated exit @status@.
The operation never returns.

<tscreen><verb>
getEnvironment :: IO [(String, String)]
</verb></tscreen>

@getEnvironment@ parses the environment variable mapping provided by
@environ@, returning @(variable, value)@ pairs. 
The operation never fails.

<tscreen><verb>
setEnvironment :: [(String, String)] -> IO ()
</verb></tscreen>

@setEnvironment@ replaces the process environment with the provided
mapping of @(variable, value)@ pairs. 

<tscreen><verb>
getEnvVar :: String -> IO String
</verb></tscreen>

@getEnvVar var@ returns the value associated with variable @var@ 
in the current environment (identical functionality provided through
standard Haskell library function @System.getEnv@).

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
The variable has no mapping in the current environment.
</descrip>

<tscreen><verb>
setEnvVar :: String -> String -> IO ()
</verb></tscreen>

@setEnvVar var val@ sets the value associated with variable @var@ 
in the current environment to be @val@.  Any previous mapping is 
superseded.

<tscreen><verb>
removeEnvVar :: String -> IO ()
</verb></tscreen>

@removeEnvVar var@ removes any value associated with variable @var@ 
in the current environment.  Deleting a variable for which there is no mapping
does not generate an error.

<tscreen><verb>
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 ()
</verb></tscreen>

@signalProcess int pid@ calls @kill@ to signal 
process @pid@ with interrupt signal @int@.

<tscreen><verb>
raiseSignal :: Signal -> IO ()
</verb></tscreen>

@raiseSignal int@ calls @kill@ to signal the current process
with interrupt signal @int@. 

<tscreen><verb>
signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
</verb></tscreen>

@signalProcessGroup int pgid@ calls @kill@ to signal 
all processes in group @pgid@ with interrupt signal @int@.

<tscreen><verb>
setStoppedChildFlag :: Bool -> IO Bool
</verb></tscreen>

@setStoppedChildFlag bool@ sets a flag which controls whether or
not the @NOCLDSTOP@ option will be used the next time a signal
handler is installed for @SIGCHLD@.  If @bool@ is @True@ (the
default), @NOCLDSTOP@ will not be used; otherwise it will be.  The
operation never fails.

<tscreen><verb>
queryStoppedChildFlag :: IO Bool
</verb></tscreen>

@queryStoppedChildFlag@ queries the flag which
controls whether or not the @NOCLDSTOP@ option will be used
the next time a signal handler is installed for @SIGCHLD@.
If @NOCLDSTOP@ will be used, it returns @False@; 
otherwise (the default) it returns @True@.  
The operation never fails.

<tscreen><verb>
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
</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@ 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
</verb></tscreen>

@getSignalMask@ calls @sigprocmask@ to determine the
set of interrupts which are currently being blocked.

<tscreen><verb>
setSignalMask :: SignalSet -> IO SignalSet
</verb></tscreen>

@setSignalMask mask@ calls @sigprocmask@ with
@SIG_SETMASK@ to block all interrupts in @mask@.  The
previous set of blocked interrupts is returned.

<tscreen><verb>
blockSignals :: SignalSet -> IO SignalSet
</verb></tscreen>

@setSignalMask mask@ calls @sigprocmask@ with
@SIG_BLOCK@ to add all interrupts in @mask@ to the
set of blocked interrupts.  The previous set of blocked interrupts is returned.

<tscreen><verb>
unBlockSignals :: SignalSet -> IO SignalSet
</verb></tscreen>

@setSignalMask mask@ calls @sigprocmask@ with
@SIG_UNBLOCK@ to remove all interrupts in @mask@ from the
set of blocked interrupts.  The previous set of blocked interrupts is returned.

<tscreen><verb>
getPendingSignals :: IO SignalSet
</verb></tscreen>

@getPendingSignals@ calls @sigpending@ to obtain
the set of interrupts which have been received but are currently blocked.

<tscreen><verb>
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@.  @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
</verb></tscreen>

@scheduleAlarm i@ calls @alarm@ to schedule a real time
alarm at least @i@ seconds in the future.

<tscreen><verb>
sleep :: Int -> IO ()
</verb></tscreen>

@sleep i@ calls @sleep@ to suspend execution of the
program until at least @i@ seconds have elapsed or a signal is
received.

<sect2>Posix Process Environment
<label id="Process Environment">
<p>
<nidx>Posix, process environment</nidx>

<tscreen><verb>
getProcessID :: IO ProcessID
</verb></tscreen>

@getProcessID@ calls @getpid@ to obtain the @ProcessID@ for
the current process.

<tscreen><verb>
getParentProcessID :: IO ProcessID
</verb></tscreen>

@getProcessID@ calls @getppid@ to obtain the @ProcessID@ for
the parent of the current process.

<tscreen><verb>
getRealUserID :: IO UserID
</verb></tscreen>

@getRealUserID@ calls @getuid@ to obtain the real @UserID@
associated with the current process.

<tscreen><verb>
getEffectiveUserID :: IO UserID
</verb></tscreen>

@getRealUserID@ calls @geteuid@ to obtain the effective
@UserID@ associated with the current process.

<tscreen><verb>
setUserID :: UserID -> IO ()
</verb></tscreen>

@setUserID uid@ calls @setuid@ to set the real, effective, and
saved set-user-id associated with the current process to @uid@.

<tscreen><verb>
getLoginName :: IO String
</verb></tscreen>

@getLoginName@ calls @getlogin@ to obtain the login name
associated with the current process.

<tscreen><verb>
getRealGroupID :: IO GroupID
</verb></tscreen>

@getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
associated with the current process.

<tscreen><verb>
getEffectiveGroupID :: IO GroupID
</verb></tscreen>

@getEffectiveGroupID@ calls @getegid@ to obtain the effective
@GroupID@ associated with the current process.

<tscreen><verb>
setGroupID :: GroupID -> IO ()
</verb></tscreen>

@setGroupID gid@ calls @setgid@ to set the real, effective, and
saved set-group-id associated with the current process to @gid@.

<tscreen><verb>
getGroups :: IO [GroupID]
</verb></tscreen>

@getGroups@ calls @getgroups@ to obtain the list of
supplementary @GroupID@s associated with the current process.

<tscreen><verb>
getEffectiveUserName :: IO String
</verb></tscreen>

@getEffectiveUserName@ calls @cuserid@ to obtain a name
associated with the effective @UserID@ of the process.

<tscreen><verb>
getProcessGroupID :: IO ProcessGroupID
</verb></tscreen>

@getProcessGroupID@ calls @getpgrp@ to obtain the
@ProcessGroupID@ for the current process.

<tscreen><verb>
createProcessGroup :: ProcessID -> IO ProcessGroupID
</verb></tscreen>

@createProcessGroup pid@ calls @setpgid@ to make
process @pid@ a new process group leader.

<tscreen><verb>
joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
</verb></tscreen>

@joinProcessGroup pgid@ calls @setpgid@ to set the
@ProcessGroupID@ of the current process to @pgid@.

<tscreen><verb>
setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
</verb></tscreen>

@setProcessGroupID pid pgid@ calls @setpgid@ to set the
@ProcessGroupID@ for process @pid@ to @pgid@.

<tscreen><verb>
createSession :: IO ProcessGroupID
</verb></tscreen>

@createSession@ calls @setsid@ to create a new session
with the current process as session leader.

<tscreen><verb>
systemName :: SystemID -> String
nodeName :: SystemID -> String
release :: SystemID -> String
version :: SystemID -> String
machine :: SystemID -> String

getSystemID :: IO SystemID
</verb></tscreen>

@getSystemID@ calls @uname@ to obtain information
about the current operating system.

<tscreen><verb>
> epochTime :: IO EpochTime
</verb></tscreen>

@epochTime@ calls @time@ to obtain the number of 
seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).

<tscreen><verb>
elapsedTime     :: ProcessTimes -> ClockTick
userTime        :: ProcessTimes -> ClockTick
systemTime      :: ProcessTimes -> ClockTick
childUserTime   :: ProcessTimes -> ClockTick
childSystemTime :: ProcessTimes -> ClockTick

getProcessTimes :: IO ProcessTimes
</verb></tscreen>

@getProcessTimes@ calls @times@ to obtain time-accounting
information for the current process and its children.

<tscreen><verb>
getControllingTerminalName :: IO FilePath
</verb></tscreen>

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

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
There is no controlling terminal, or its name cannot be determined.
<tag>@SystemError@</tag>
Various other causes.
</descrip>

<tscreen><verb>
getTerminalName :: Fd -> IO FilePath
</verb></tscreen>

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

The operation may fail with:

<descrip>
<tag>@InappropriateType@</tag>
The channel is not associated with a terminal.
<tag>@NoSuchThing@</tag>
The channel is associated with a terminal, but it has no name.
<tag>@SystemError@</tag>
Various other causes.
</descrip>

<tscreen><verb>
queryTerminal :: Fd -> IO Bool
</verb></tscreen>

@queryTerminal fd@ calls @isatty@ to determine whether or
not @Fd@ @fd@ is associated with a terminal.

<tscreen><verb>
getSysVar :: SysVar -> IO Limit
</verb></tscreen>

@getSysVar var@ calls @sysconf@ to obtain the
dynamic value of the requested configurable system limit or option.
For defined system limits, @getSysVar@ returns the associated
value.  For defined system options, the result of @getSysVar@
is undefined, but not failure.

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
The requested system limit or option is undefined.
</descrip>

<sect2>Posix operations on files and directories
<label id="Files and Directories">
<p>
<nidx>Posix, files and directories</nidx>

<tscreen><verb>
openDirStream :: FilePath -> IO DirStream
</verb></tscreen>

@openDirStream dir@ calls @opendir@ to obtain a
directory stream for @dir@.

<tscreen><verb>
readDirStream :: DirStream -> IO String
</verb></tscreen>

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

The operation may fail with:

<descrip>
<tag>@EOF@</tag>
End of file has been reached.
<tag>@SystemError@</tag>
Various other causes.
</descrip>

<tscreen><verb>
rewindDirStream :: DirStream -> IO ()
</verb></tscreen>

@rewindDirStream dp@ calls @rewinddir@ to reposition
the directory stream @dp@ at the beginning of the directory.

<tscreen><verb>
closeDirStream :: DirStream -> IO ()
</verb></tscreen>

@closeDirStream dp@ calls @closedir@ to close
the directory stream @dp@.

<tscreen><verb>
getWorkingDirectory :: IO FilePath
</verb></tscreen>

@getWorkingDirectory@ calls @getcwd@ to obtain the name
of the current working directory.

<tscreen><verb>
changeWorkingDirectory :: FilePath -> IO ()
</verb></tscreen>

@changeWorkingDirectory dir@ calls @chdir@ to change
the current working directory to @dir@.

<tscreen><verb>
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
</verb></tscreen>

@openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)@ calls
@open@ to obtain a @Fd@ for the file @path@ with access
mode @acc@.  If @mode@ is @Just m@, the @O_CREAT@ flag is
set and the file's permissions will be based on @m@ if it does not
already exist; otherwise, the @O_CREAT@ flag is not set.  The
arguments @app@, @excl@, @noctty@, @nonblock@, and
@trunc@ control whether or not the flags @O_APPEND@,
@O_EXCL@, @O_NOCTTY@, @O_NONBLOCK@, and @O_TRUNC@ are set,
respectively.

<tscreen><verb>
createFile :: FilePath -> FileMode -> IO Fd
</verb></tscreen>

@createFile path mode@ calls @creat@ to obtain a @Fd@
for file @path@, which will be created with permissions based on
@mode@ if it does not already exist.

<tscreen><verb>
setFileCreationMask :: FileMode -> IO FileMode
</verb></tscreen>

@setFileCreationMask mode@ calls @umask@ to set
the process's file creation mask to @mode@.  The previous file
creation mask is returned.

<tscreen><verb>
createLink :: FilePath -> FilePath -> IO ()
</verb></tscreen>

@createLink old new@ calls @link@ to create a 
new path, @new@, linked to an existing file, @old@.
<tscreen><verb>
createDirectory :: FilePath -> FileMode -> IO ()
</verb></tscreen>

@createDirectory dir mode@ calls @mkdir@ to 
create a new directory, @dir@, with permissions based on
@mode@.

<tscreen><verb>
createNamedPipe :: FilePath -> FileMode -> IO ()
</verb></tscreen>

@createNamedPipe fifo mode@ calls @mkfifo@ to 
create a new named pipe, @fifo@, with permissions based on
@mode@.

<tscreen><verb>
removeLink :: FilePath -> IO ()
</verb></tscreen>

@removeLink path@ calls @unlink@ to remove the link
named @path@.

<tscreen><verb>
removeDirectory :: FilePath -> IO ()
</verb></tscreen>

@removeDirectory dir@ calls @rmdir@ to remove the 
directory named @dir@.

<tscreen><verb>
rename :: FilePath -> FilePath -> IO ()
</verb></tscreen>

@rename old new@ calls @rename@ to rename a 
file or directory from @old@ to @new@.

<tscreen><verb>
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
</verb></tscreen>

@getFileStatus path@ calls @stat@ to get the
@FileStatus@ information for the file @path@.

<tscreen><verb>
getFdStatus :: Fd -> IO FileStatus
</verb></tscreen>

@getFdStatus fd@ calls @fstat@ to get the
@FileStatus@ information for the file associated with
@Fd@ @fd@.

<tscreen><verb>
queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
</verb></tscreen>

@queryAccess path r w x@ calls @access@ to test the access
permissions for file @path@.  The three arguments, @r@, @w@,
and @x@ control whether or not @access@ is called with
@R_OK@, @W_OK@, and @X_OK@ respectively.

<tscreen><verb>
queryFile :: FilePath -> IO Bool
</verb></tscreen>

@queryFile path@ calls @access@ with @F_OK@ to test for the
existence for file @path@.

<tscreen><verb>
setFileMode :: FilePath -> FileMode -> IO ()
</verb></tscreen>

@setFileMode path mode@ calls @chmod@ to set the
permission bits associated with file @path@ to @mode@.

<tscreen><verb>
setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
</verb></tscreen>

@setOwnerAndGroup path uid gid@ calls @chown@ to
set the @UserID@ and @GroupID@ associated with file
@path@ to @uid@ and @gid@, respectively.

<tscreen><verb>
setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
</verb></tscreen>

@setFileTimes path atime mtime@ calls @utime@ to
set the access and modification times associated with file
@path@ to @atime@ and @mtime@, respectively.

<tscreen><verb>
touchFile :: FilePath -> IO ()
</verb></tscreen>

@touchFile path@ calls @utime@ to
set the access and modification times associated with file
@path@ to the current time.

<tscreen><verb>
getPathVar :: PathVar -> FilePath -> IO Limit
</verb></tscreen>

@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.
The operation may fail with:
<descrip>
<tag>@NoSuchThing@</tag>
The requested file limit or option is undefined.
<tag>@SystemError@</tag>
Various other causes.
</descrip>


<tscreen><verb>
getFdVar :: PathVar -> Fd -> IO Limit
</verb></tscreen>

@getFdVar 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, @getFdVar@ returns the associated
value.  For defined file options, the result of @getFdVar@
is undefined, but not failure.

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
The requested file limit or option is undefined.
<tag>@SystemError@</tag>
Various other causes.
</descrip>

<sect2>Posix Input and Output Primitives
<label id="Input/Output">
<p>
<nidx>Posix, input/output</nidx>

<tscreen><verb>
createPipe :: IO (Fd, Fd)
</verb></tscreen>

@createPipe@ calls @pipe@ to create a pipe and returns a pair of
@Fd@s, the first for reading and the second for writing.

<tscreen><verb>
dup :: Fd -> IO Fd
</verb></tscreen>

@dup fd@ calls @dup@ to duplicate @Fd@ @fd@ to
another @Fd@.

<tscreen><verb>
dupTo :: Fd -> Fd -> IO ()
</verb></tscreen>

@dupTo src dst@ calls @dup2@ to duplicate @Fd@
@src@ to @Fd@ @dst@.

<tscreen><verb>
fdClose :: Fd -> IO ()
</verb></tscreen>

@fdClose fd@ calls @close@ to close @Fd@ @fd@.

<tscreen><verb>
fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
</verb></tscreen>

@fdRead fd nbytes@ calls @read@ to read at most @nbytes@
bytes from @Fd@ @fd@, and returns the result as a string
paired with the number of bytes actually read.

The operation may fail with:

<descrip>
<tag>@EOF@</tag>
End of file has been reached.
<tag>@SystemError@</tag>
Various other causes.
</descrip>

<tscreen><verb>
fdWrite :: Fd -> String -> IO ByteCount
</verb></tscreen>

@fdWrite fd s@ calls @write@ to write
the string @s@ to @Fd@ @fd@ as a
contiguous sequence of bytes.  It returns the number of bytes successfully
written.

<tscreen><verb>
queryFdOption :: FdOption -> Fd -> IO Bool
</verb></tscreen>

@getFdOption opt fd@ calls @fcntl@ to determine whether or
not the flag associated with @FdOption@ @opt@ is set for
@Fd@ @fd@.

<tscreen><verb>
setFdOption :: Fd -> FdOption -> Bool -> IO ()
</verb></tscreen>

@setFdOption fd opt val@ calls @fcntl@ to set the flag
associated with @FdOption@ @opt@ on @Fd@ @fd@ to
@val@.

<tscreen><verb>
getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
</verb></tscreen>

@getLock fd lock@ calls @fcntl@ to get the first @FileLock@
for @Fd@ @fd@ which blocks the @FileLock@ @lock@.  If
no such @FileLock@ exists, @getLock@ returns @Nothing@.
Otherwise, it returns @Just (pid, block)@, where @block@ is the
blocking @FileLock@ and @pid@ is the @ProcessID@ of the
process holding the blocking @FileLock@.


<tscreen><verb>
setLock :: Fd -> FileLock -> IO ()
</verb></tscreen>

@setLock fd lock@ calls @fcntl@ with @F_SETLK@ to set or
clear a lock segment for @Fd@ @fd@ as indicated by the
@FileLock@ @lock@.  @setLock@ does not block, but fails with
@SystemError@ if the request cannot be satisfied immediately.

<tscreen><verb>
waitToSetLock :: Fd -> FileLock -> IO ()
</verb></tscreen>

@waitToSetLock fd lock@ calls @fcntl@ with @F_SETLKW@ to set
or clear a lock segment for @Fd@ @fd@ as indicated by the
@FileLock@ @lock@. If the request cannot be satisfied
immediately, @waitToSetLock@ blocks until the request can be
satisfied.


<tscreen><verb>
fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
</verb></tscreen>

@fdSeek fd whence offset@ calls @lseek@ to position the
@Fd@ @fd@ at the given @offset@ from the starting location
indicated by @whence@.  It returns the resulting offset from the
start of the file in bytes.

<sect2>Posix, Device- and Class-Specific Functions
<label id="Device Specific Functions">
<p>
<nidx>Posix, device and class-specific functions</nidx>

<tscreen><verb>
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
</verb></tscreen>

@getTerminalAttributes fd@ calls @tcgetattr@ to obtain
the @TerminalAttributes@ associated with @Fd@ @fd@.

<tscreen><verb>
setTerminalAttributes :: Fd
                      -> TerminalAttributes 
                      -> TerminalState
                      -> IO ()
</verb></tscreen>

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

<tscreen><verb>
sendBreak :: Fd -> Int -> IO ()
</verb></tscreen>

@sendBreak fd duration@ calls @tcsendbreak@ to transmit a
continuous stream of zero-valued bits on @Fd@ @fd@ for the
specified implementation-dependent @duration@.

<tscreen><verb>
drainOutput :: Fd -> IO ()
</verb></tscreen>

@drainOutput fd@ calls @tcdrain@ to block until all output
written to @Fd@ @fd@ has been transmitted.

<tscreen><verb>
discardData :: Fd -> QueueSelector -> IO ()
</verb></tscreen>

@discardData fd queues@ calls @tcflush@ to discard
pending input and/or output for @Fd@ @fd@,
as indicated by the @QueueSelector@ @queues@.

<tscreen><verb>
controlFlow :: Fd -> FlowAction -> IO ()
</verb></tscreen>

@controlFlow fd action@ calls @tcflow@ to control the 
flow of data on @Fd@ @fd@, as indicated by
@action@.

<tscreen><verb>
getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
</verb></tscreen>

@getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
obtain the @ProcessGroupID@ of the foreground process group 
associated with the terminal attached to @Fd@ @fd@.

<tscreen><verb>
setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
</verb></tscreen>

@setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
set the @ProcessGroupID@ of the foreground process group 
associated with the terminal attached to @Fd@ 
@fd@ to @pgid@.

<sect2>Posix System Databases
<label id="System Database">
<p>
<nidx>Posix, system databases</nidx>

<tscreen><verb>
groupName    :: GroupEntry -> String
groupID      :: GroupEntry -> GroupID
groupMembers :: GroupEntry -> [String]

getGroupEntryForID :: GroupID -> IO GroupEntry
</verb></tscreen>

@getGroupEntryForID gid@ calls @getgrgid@ to obtain
the @GroupEntry@ information associated with @GroupID@
@gid@.

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
There is no group entry for the GroupID.
</descrip>

<tscreen><verb>
getGroupEntryForName :: String -> IO GroupEntry
</verb></tscreen>

@getGroupEntryForName name@ calls @getgrnam@ to obtain
the @GroupEntry@ information associated with the group called
@name@.

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
There is no group entry for the name.
</descrip>

<tscreen><verb>
userName      :: UserEntry -> String
userID        :: UserEntry -> UserID
userGroupID   :: UserEntry -> GroupID
homeDirectory :: UserEntry -> String
userShell     :: UserEntry -> String

getUserEntryForID :: UserID -> IO UserEntry
</verb></tscreen>

@getUserEntryForID gid@ calls @getpwuid@ to obtain
the @UserEntry@ information associated with @UserID@
@uid@.
The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
There is no user entry for the UserID.
</descrip>

<tscreen><verb>
getUserEntryForName :: String -> IO UserEntry
</verb></tscreen>

@getUserEntryForName name@ calls @getpwnam@ to obtain
the @UserEntry@ information associated with the user login
@name@.

The operation may fail with:

<descrip>
<tag>@NoSuchThing@</tag>
There is no user entry for the name.
</descrip>

<sect2>POSIX Errors
<label id="Error reporting and handling">
<p>
<nidx>Posix, errors</nidx>

<tscreen><verb>
getErrorCode :: IO ErrorCode
</verb></tscreen>

@getErrorCode@ returns the current value of the external
variable @errno@.  It never fails.

<tscreen><verb>
setErrorCode :: ErrorCode -> IO ()
</verb></tscreen>

@setErrorCode err@ sets the external
variable @errno@ to @err@.  It never fails.

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

</verb></tscreen>