A straightforward wrapping of unix APIs for Haskell.
I wrote this package because state of posix API support in Haskell is
somewhat unsatisfactory in a few ways:
* There are many syscalls not covered by the `unix` package
* The `unix` package needlessly renames syscalls, making them harder to
find for people familiar with the posix API. For example, `lstat` has
been renamed to `getSymbolicLinkStatus`
* There are a large number of packages that fill in various holes, but
you have to scrape them together.
The goal of this package then, is to provide a one-stop-shop for unix
API bindings, with a straightforward mapping to the underlying C API.
At the time of writing there are many syscalls missing, but in theory
most things belong here. Patches welcome; see the section below re:
how to add a syscall.
# General Conventions
* Function names are the same as the underlying system calls, so there
is no guesswork.
* Wrappers automatically retry on `EINTR` where appropriate (this is
safe for most system calls, but not all, e.g. `close` on Linux).
* The basic versions of the syscalls return `IO (Either Errno a)`,
rather than raising an exception.
* Each system call also has a variant suffixed with `Exn` that throws
exceptions.
* We define a type alias `type EIO a = IO (Either Errno a)` for
convenience.
* For flags, we add newtype wrappers, and they can be combined with
their `SemiGroup` instances, e.g.
* `open "hello.txt" (o_CREAT <> o_RDWR) 0o600`
* Flags are named the same as the C constant, but with the first
character lower-cased.
* For functions that take a buffer, we instead accept a `ByteString`
when the buffer is read, or return one when it is written, e.g.
* `read :: Fd -> Int -> EIO BS.ByteString`
* `write :: Fd -> BS.ByteString -> EIO CSsize`
* We also provide variants suffixed with `Buf`, that take a pointer and
size:
* `readBuf :: Fd -> Ptr Word8 -> CSize -> EIO CSsize`
* We provide a `CString` type for functions which accept strings as
arguments. This type is an instance of `IsString`, so you can use
string literals if you enable `OverloadedStrings`, or use the
`fromString` function to convert. The conversion uses utf-8 encoding.
* For some calls we also add obvious convenience helpers, e.g.
`readFull` and `writeFull`, which wrap `read` and `write` and handle
short reads and writes for the caller.
# Contributing
## Adding a syscall
To add a new system call:
* Add the appropriate declaration to `Unix.C`, following conventions
established by the examples in that file.
* Add a wrapper following the general conventions in `Unix`.