\item The GHC system library - collection of interfaces that mainly
have grown out of abstractions used to implement GHC itself.
\item Parts of the HBC libraries.
-\item The Posix interface - a quality interface to OS functionality as
-specified by {\tt POSIX 1003.1}. Sadly, this library hasn't made it
-into a standard Haskell library.
+\item The Posix interface - a mostly complete interface to OS functionality as
+specified by {\tt POSIX 1003.1}. Sadly, this library isn't a standard
+Haskell library...yet.
\item The contrib libraries - oodles of numeric codes..
\end{itemize}
%* *
%************************************************************************
-You need to \tr{import PackedString} and heave in your \tr{-syslib
-ghc} to use \tr{PackedString}s.
+You need to \tr{import PackedString} and heave in your
+\tr{-syslib ghc} to use \tr{PackedString}s.
The basic type and functions available are:
\begin{verbatim}
\end{verbatim}
Various examples of networking Haskell code are provided in
-\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs.
+%\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs.
%************************************************************************
%* *
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} - IEEE Std. 1003.1). The
-interface is accessed by \tr{import Posix} and adding \tr{-syslib
-posix} on your command-line.
+interface is accessed by \tr{import Posix} and adding
+\tr{-syslib posix} on your command-line.
-\subsubsection[Posix-data-types]{Posix data types}
+\subsubsection[Posix data types]{Posix data types}
\index{Posix, data types}
be an arithmetic type.
\begin{verbatim}
-> data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
+data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
\end{verbatim}
A \tr{EpochTime} is a primitive of type \tr{time_t}, which is
| B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
deriving (Eq, Show)
-type Channel = Int
+data Fd
-data ChannelOption = AppendOnWrite
- | CloseOnExec
- | NonBlockingRead
+intToFd :: Int -> Fd -- use with care.
+
+data FdOption = AppendOnWrite
+ | CloseOnExec
+ | NonBlockingRead
data ControlCharacter = EndOfFile
| EndOfLine
deriving (Eq, Show)
\end{verbatim}
-\subsubsection{posix-process-env}{Posix Process Primitives}
+\subsubsection[Process Primitives]{Posix Process Primitives}
\begin{verbatim}
forkProcess :: IO (Maybe ProcessID)
\end{verbatim}
\tr{forkProcess} calls \tr{fork}, returning
-\tr{Just pid} to the parent, where <var>pid</var> is the
+\tr{Just pid} to the parent, where \tr{pid} is the
ProcessID of the child, and returning \tr{Nothing} to the
child.
\tr{wd} is \tr{Just dir}, the command is executed with working
directory \tr{dir}; otherwise, the command is executed in the current
working directory. If \tr{{in,out,err}hdl} is \tr{Just handle}, the
-command is executed with the \tr{Channel} for \tr{std{in,out,err}}
-attached to the specified \tr{handle}; otherwise, the \tr{Channel} for
+command is executed with the \tr{Fd} for \tr{std{in,out,err}}
+attached to the specified \tr{handle}; otherwise, the \tr{Fd} for
\tr{std{in,out,err}} is left unchanged.
\begin{verbatim}
\tr{installHandler int handler iset} calls \tr{sigaction} to install
an interrupt handler for signal \tr{int}. If \tr{handler} is
\tr{Default}, \tr{SIG_DFL} is installed; if \tr{handler} is
-\tr{Ignore}, \tr{SIG_IGN} is installed; if \tr{handler} is \tr{Catch
-action}, a handler is installed which will invoke \tr{action} as a
+\tr{Ignore}, \tr{SIG_IGN} is installed; if \tr{handler} is
+\tr{Catch action}, a handler is installed which will invoke \tr{action} as a
replacement for \tr{main}. If \tr{iset} is \tr{Just s}, then the
\tr{sa_mask} of the \tr{sigaction} structure is set to \tr{s};
otherwise it is cleared. The previously installed signal handler for
program until at least \tr{i} seconds have elapsed or a signal is
received.
-\subsubsection[posix-proc-env]{Posix Process Environment}
+\subsubsection[Process Environment]{Posix Process Environment}
\index{Posix, process environment}
\begin{verbatim}
\end{itemize}
\begin{verbatim}
-getTerminalName :: Channel -> IO FilePath
+getTerminalName :: Fd -> IO FilePath
\end{verbatim}
\tr{getTerminalName fd} calls \tr{ttyname} to obtain a name associated
-with the terminal for \tr{Channel} \tr{fd}. If \tr{fd} is associated
+with the terminal for \tr{Fd} \tr{fd}. If \tr{fd} is associated
with a terminal, \tr{getTerminalName} returns the name of the
terminal.
\end{itemize}
\begin{verbatim}
-queryTerminal :: Channel -> IO Bool
+queryTerminal :: Fd -> IO Bool
\end{verbatim}
\tr{queryTerminal fd} calls \tr{isatty} to determine whether or
-not \tr{Channel} \tr{fd} is associated with a terminal.
+not \tr{Fd} \tr{fd} is associated with a terminal.
\begin{verbatim}
getSysVar :: SysVar -> IO Limit
The requested system limit or option is undefined.
\end{itemize}
-\subsubsection[posix-files-dir]{Files and Directories}
+\subsubsection[Files and Directories]{Posix operations on files and directories}
\index{Posix, files and directories}
\begin{verbatim}
unionFileModes :: FileMode -> FileMode -> FileMode
intersectFileModes :: FileMode -> FileMode -> FileMode
-stdInput :: Channel
-stdInput = 0
+stdInput :: Fd
+stdInput = intToFd 0
+
+stdOutput :: Fd
+stdOutput = intToFd 1
-stdOutput :: Channel
-stdOutput = 1
+stdError :: Fd
+stdError = intToFd 2
-stdError :: Channel
-stdError = 2
+data OpenFileFlags =
+ OpenFileFlags {
+ append :: Bool,
+ exclusive :: Bool,
+ noctty :: Bool,
+ nonBlock :: Bool,
+ trunc :: Bool
+ }
-openChannel :: FilePath
- -> OpenMode
- -> Maybe FileMode -- Just x => O_CREAT, Nothing => must exist
- -> Bool -- O_APPEND
- -> Bool -- O_EXCL
- -> Bool -- O_NOCTTY
- -> Bool -- O_NONBLOCK
- -> Bool -- O_TRUNC
- -> IO Channel
+openFd :: FilePath
+ -> OpenMode
+ -> Maybe FileMode -- Just x => O_CREAT, Nothing => must exist
+ -> OpenFileFlags
+ -> IO Fd
\end{verbatim}
-\tr{openChannel path acc mode app excl noctty nonblock trunc} calls
-\tr{open} to obtain a \tr{Channel} for the file \tr{path} with access
+\tr{openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)} calls
+\tr{open} to obtain a \tr{Fd} for the file \tr{path} with access
mode \tr{acc}. If \tr{mode} is \tr{Just m}, the \tr{O_CREAT} flag is
set and the file's permissions will be based on \tr{m} if it does not
already exist; otherwise, the \tr{O_CREAT} flag is not set. The
respectively.
\begin{verbatim}
-createFile :: FilePath -> FileMode -> IO Channel
+createFile :: FilePath -> FileMode -> IO Fd
\end{verbatim}
-\tr{createFile path mode} calls \tr{creat} to obtain a \tr{Channel}
+\tr{createFile path mode} calls \tr{creat} to obtain a \tr{Fd}
for file \tr{path}, which will be created with permissions based on
\tr{mode} if it does not already exist.
\tr{FileStatus} information for the file \tr{path}.
\begin{verbatim}
-getChannelStatus :: Channel -> IO FileStatus
+getFdStatus :: Fd -> IO FileStatus
\end{verbatim}
-\tr{getChannelStatus fd} calls \tr{fstat} to get the
+\tr{getFdStatus fd} calls \tr{fstat} to get the
\tr{FileStatus} information for the file associated with
-\tr{Channel} \tr{fd}.
+\tr{Fd} \tr{fd}.
\begin{verbatim}
queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
\begin{verbatim}
-getChannelVar :: PathVar -> Channel -> IO Limit
+getFdVar :: PathVar -> Fd -> IO Limit
\end{verbatim}
-\tr{getChannelVar var fd} calls \tr{fpathconf} to obtain the
+\tr{getFdVar var fd} calls \tr{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 \tr{fd}.
-For defined file limits, \tr{getChannelVar} returns the associated
-value. For defined file options, the result of \tr{getChannelVar}
+For defined file limits, \tr{getFdVar} returns the associated
+value. For defined file options, the result of \tr{getFdVar}
is undefined, but not failure.
The operation may fail with:
Various other causes.
\end{itemize}
-\subsubsection[posix-input-output]{Posix Input and Output Primitives}
+\subsubsection[Inut Output]{Posix Input and Output Primitives}
\index{Posix, input/output}
\begin{verbatim}
-createPipe :: IO (Channel, Channel)
+createPipe :: IO (Fd, Fd)
\end{verbatim}
\tr{createPipe} calls \tr{pipe} to create a pipe and returns a pair of
-\tr{Channels}, the first for writing and the second for reading.
+\tr{Fd}s, the first for writing and the second for reading.
\begin{verbatim}
-dupChannel :: Channel -> IO Channel
+dup :: Fd -> IO Fd
\end{verbatim}
-\tr{dupChannel fd} calls \tr{dup} to duplicate \tr{Channel} \tr{fd} to
-another \tr{Channel}.
+\tr{dup fd} calls \tr{dup} to duplicate \tr{Fd} \tr{fd} to
+another \tr{Fd}.
\begin{verbatim}
-dupChannelTo :: Channel -> Channel -> IO ()
+dupTo :: Fd -> Fd -> IO ()
\end{verbatim}
-\tr{dupChannelTo src dst} calls \tr{dup2} to duplicate \tr{Channel}
-\tr{src} to \tr{Channel} \tr{dst}.
+\tr{dupTo src dst} calls \tr{dup2} to duplicate \tr{Fd}
+\tr{src} to \tr{Fd} \tr{dst}.
\begin{verbatim}
-closeChannel :: Channel -> IO ()
+fdClose :: Fd -> IO ()
\end{verbatim}
-\tr{closeChannel fd} calls \tr{close} to close \tr{Channel} \tr{fd}.
+\tr{fdClose fd} calls \tr{close} to close \tr{Fd} \tr{fd}.
\begin{verbatim}
-readChannel :: Channel -> ByteCount -> IO (String, ByteCount)
+fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
\end{verbatim}
-\tr{readChannel fd nbytes} calls \tr{read} to read at most \tr{nbytes}
-bytes from \tr{Channel} \tr{fd}, and returns the result as a string
+\tr{fdRead fd nbytes} calls \tr{read} to read at most \tr{nbytes}
+bytes from \tr{Fd} \tr{fd}, and returns the result as a string
paired with the number of bytes actually read.
The operation may fail with:
\end{itemize}
\begin{verbatim}
-writeChannel :: Channel -> String -> IO ByteCount
+fdWrite :: Fd -> String -> IO ByteCount
\end{verbatim}
-\tr{writeChannel fd s} calls \tr{write} to write
-the string \tr{s} to \tr{Channel} \tr{fd} as a
+\tr{fdWrite fd s} calls \tr{write} to write
+the string \tr{s} to \tr{Fd} \tr{fd} as a
contiguous sequence of bytes. It returns the number of bytes successfully
written.
\begin{verbatim}
-queryChannelOption :: ChannelOption -> Channel -> IO Bool
+queryFdOption :: FdOption -> Fd -> IO Bool
\end{verbatim}
-\tr{getChannelOption opt fd} calls \tr{fcntl} to determine whether or
-not the flag associated with \tr{ChannelOption} \tr{opt} is set for
-\tr{Channel} \tr{fd}.
+\tr{getFdOption opt fd} calls \tr{fcntl} to determine whether or
+not the flag associated with \tr{FdOption} \tr{opt} is set for
+\tr{Fd} \tr{fd}.
\begin{verbatim}
-setChannelOption :: ChannelOption -> Bool -> Channel -> IO ()
+setFdOption :: Fd -> FdOption -> Bool -> IO ()
\end{verbatim}
-\tr{setChannelOption opt val fd} calls \tr{fcntl} to set the flag
-associated with \tr{ChannelOption} \tr{opt} on \tr{Channel} \tr{fd} to
+\tr{setFdOption fd opt val} calls \tr{fcntl} to set the flag
+associated with \tr{FdOption} \tr{opt} on \tr{Fd} \tr{fd} to
\tr{val}.
\begin{verbatim}
-getLock :: Channel -> FileLock -> IO (Maybe (ProcessID, FileLock))
+getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
\end{verbatim}
\tr{getLock fd lock} calls \tr{fcntl} to get the first \tr{FileLock}
-for \tr{Channel} \tr{fd} which blocks the \tr{FileLock} \tr{lock}. If
+for \tr{Fd} \tr{fd} which blocks the \tr{FileLock} \tr{lock}. If
no such \tr{FileLock} exists, \tr{getLock} returns \tr{Nothing}.
Otherwise, it returns \tr{Just (pid, block)}, where \tr{block} is the
blocking \tr{FileLock} and \tr{pid} is the \tr{ProcessID} of the
\begin{verbatim}
-setLock :: Channel -> FileLock -> IO ()
+setLock :: Fd -> FileLock -> IO ()
\end{verbatim}
\tr{setLock fd lock} calls \tr{fcntl} with \tr{F_SETLK} to set or
-clear a lock segment for \tr{Channel} \tr{fd} as indicated by the
+clear a lock segment for \tr{Fd} \tr{fd} as indicated by the
\tr{FileLock} \tr{lock}. \tr{setLock} does not block, but fails with
\tr{SystemError} if the request cannot be satisfied immediately.
\begin{verbatim}
-waitToSetLock :: Channel -> FileLock -> IO ()
+waitToSetLock :: Fd -> FileLock -> IO ()
\end{verbatim}
\tr{waitToSetLock fd lock} calls \tr{fcntl} with \tr{F_SETLKW} to set
-or clear a lock segment for \tr{Channel} \tr{fd} as indicated by the
+or clear a lock segment for \tr{Fd} \tr{fd} as indicated by the
\tr{FileLock} \tr{lock}. If the request cannot be satisfied
immediately, \tr{waitToSetLock} blocks until the request can be
satisfied.
\begin{verbatim}
-seekChannel :: Channel -> SeekMode -> FileOffset -> IO FileOffset
+fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
\end{verbatim}
-\tr{seekChannel fd whence offset} calls \tr{lseek} to position the
-\tr{Channel} at the given \tr{offset} from the starting location
+\tr{fdSeek fd whence offset} calls \tr{lseek} to position the
+\tr{Fd} \tr{fd} at the given \tr{offset} from the starting location
indicated by \tr{whence}. It returns the resulting offset from the
start of the file in bytes.
-\subsubsection[posix-device-class]{Posix, Device- and Class-Specific Functions}
+\subsubsection[Device Specific Functions]{Posix, Device- and Class-Specific Functions}
\index{Posix, device and class-specific functions}
\begin{verbatim}
outputSpeed :: TerminalAttributes -> BaudRate
withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
-getTerminalAttributes :: Channel -> IO TerminalAttributes
+getTerminalAttributes :: Fd -> IO TerminalAttributes
\end{verbatim}
\tr{getTerminalAttributes fd} calls \tr{tcgetattr} to obtain
-the \tr{TerminalAttributes} associated with \tr{Channel}
-\tr{fd}.
+the \tr{TerminalAttributes} associated with \tr{Fd} \tr{fd}.
\begin{verbatim}
-setTerminalAttributes :: Channel
+setTerminalAttributes :: Fd
-> TerminalAttributes
-> TerminalState
-> IO ()
\end{verbatim}
\tr{setTerminalAttributes fd attr ts} calls \tr{tcsetattr} to change
-the \tr{TerminalAttributes} associated with \tr{Channel} \tr{fd} to
+the \tr{TerminalAttributes} associated with \tr{Fd} \tr{fd} to
\tr{attr}, when the terminal is in the state indicated by \tr{ts}.
\begin{verbatim}
-sendBreak :: Channel -> Int -> IO ()
+sendBreak :: Fd -> Int -> IO ()
\end{verbatim}
\tr{sendBreak fd duration} calls \tr{tcsendbreak} to transmit a
-continuous stream of zero-valued bits on \tr{Channel} \tr{fd} for the
+continuous stream of zero-valued bits on \tr{Fd} \tr{fd} for the
specified implementation-dependent \tr{duration}.
\begin{verbatim}
-drainOutput :: Channel -> IO ()
+drainOutput :: Fd -> IO ()
\end{verbatim}
\tr{drainOutput fd} calls \tr{tcdrain} to block until all output
-written to \tr{Channel} \tr{fd} has been transmitted.
+written to \tr{Fd} \tr{fd} has been transmitted.
\begin{verbatim}
-discardData :: Channel -> QueueSelector -> IO ()
+discardData :: Fd -> QueueSelector -> IO ()
\end{verbatim}
\tr{discardData fd queues} calls \tr{tcflush} to discard
-pending input and/or output for \tr{Channel} \tr{fd},
+pending input and/or output for \tr{Fd} \tr{fd},
as indicated by the \tr{QueueSelector} \tr{queues}.
\begin{verbatim}
-controlFlow :: Channel -> FlowAction -> IO ()
+controlFlow :: Fd -> FlowAction -> IO ()
\end{verbatim}
\tr{controlFlow fd action} calls \tr{tcflow} to control the
-flow of data on \tr{Channel} \tr{fd}, as indicated by
+flow of data on \tr{Fd} \tr{fd}, as indicated by
\tr{action}.
\begin{verbatim}
-getTerminalProcessGroupID :: Channel -> IO ProcessGroupID
+getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
\end{verbatim}
\tr{getTerminalProcessGroupID fd} calls \tr{tcgetpgrp} to
obtain the \tr{ProcessGroupID} of the foreground process group
-associated with the terminal attached to \tr{Channel}
-\tr{fd}.
+associated with the terminal attached to \tr{Fd} \tr{fd}.
\begin{verbatim}
-setTerminalProcessGroupID :: Channel -> ProcessGroupID -> IO ()
+setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
\end{verbatim}
\tr{setTerminalProcessGroupID fd pgid} calls \tr{tcsetpgrp} to
set the \tr{ProcessGroupID} of the foreground process group
-associated with the terminal attached to \tr{Channel}
+associated with the terminal attached to \tr{Fd}
\tr{fd} to \tr{pgid}.
-\subsubsection[posix-system-db]{Posix System Databases}
+\subsubsection[System Database]{Posix System Databases}
\index{Posix, system databases}
\begin{verbatim}
There is no user entry for the name.
\end{itemize}
-\subsubsection[posix-errors]{POSIX Errors}
+\subsubsection[Error reporting and handling]{POSIX Errors}
\index{Posix, errors}
\begin{verbatim}
noError = 0
argumentListTooLong, e2BIG :: ErrorCode
-badChannel, eBADF :: ErrorCode
+badFd, eBADF :: ErrorCode
brokenPipe, ePIPE :: ErrorCode
directoryNotEmpty, eNOTEMPTY :: ErrorCode
execFormatError, eNOEXEC :: ErrorCode
byteToInt :: Byte -> Int -- convert a Byte to Int
\end{verbatim}
-\item[\tr{Time}:]
+\item[\tr{TimeUtil}:]
\index{Time module (HBC library)}%
Manipulate time values (a Double with seconds since 1970).
+[7/97 -- this lib has been more or less superceeded by the standard Time
+ interface]
+
\begin{verbatim}
-- year mon day hour min sec dec-sec weekday
data Time = Time Int Int Int Int Int Int Double Int
projects / ghc-hetmet.git / blobdiff