posix-api: posix bindings

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

'ghc-options: -O2' is rarely needed. Check that it is giving a real benefit and not just imposing longer compile times on your users.

This library provides a very thin wrapper around POSIX APIs. It can be compiled on any operating system that implements the standard as specified in IEEE Std 1003.1 faithfully. It has similar goals as the unix package, but its design differs in several areas:

ByteArray and Addr are used pervasively. There is no use of String in this library.
Functions do not throw errors. This library uses `IO (Either Errno a)` in places where unix would use `IO a`.
The numeric types from Foreign.C.Types and System.Posix.Types are used in the type signatures of functions so that a haskell function's type signature matches its underlying POSIX equivalent exactly.
Flags are newtypes over CInt (or whatever integral type matches the posix specification) rather than enumerations. The data constructors are exported, making the types extensible for operating system that have additional flags.

About a dozen other packages offers wrappers for some subset of the POSIX specification are strewn across hackage. They include `regex-posix`, `posix-paths`, `posix-timer`, `posix-socket`, `posix-filelock`, `posix-acl`, etc. This library differs from all off these in various ways. Here are some of the design guidelines followed here that distinguish this package from some or all of these others:

Scope. Although this library does not include all APIs specified by POSIX, it welcomes as many of them as anyone is willing to implement.
Monomorphization. Effectful functions in this library return their results in IO rather than using a type that involves MonadIO or MonadBaseControl.
Typeclass avoidance. This library does not introduce new typeclasses. Overloading is eschewed in favor of providing multiple functions with distinct names.
Minimality. Functions wrapping the POSIX APIs do little more than wrap the underlying functions. The major deviation here is that, when applicable, the wrappers allocate buffers are the underlying functions fill. This eschews C's characteristic buffer-passing in favor of the Haskell convention of allocating internally and returning. A more minor deviation is that for safe FFI calls, this library will perform additional work to ensure that only pinned byte arrays are handed over.

Unlike network, this sockets API in this library does not integrate sockets with GHC's event manager. This is geared toward an audience that understands how to use threadWaitRead and threadWaitWrite with unsafe FFI calls to avoid blocking the runtime.

[Skip to Readme]

Properties

Versions	0.1.0.0, 0.2.0.0, 0.2.0.0, 0.2.1.0, 0.3.0.0, 0.3.2.0, 0.3.3.0, 0.3.4.0, 0.3.5.0, 0.4.0.0, 0.4.0.1, 0.5.0.0, 0.6.0.0, 0.6.0.1, 0.6.1.0, 0.7.0.0, 0.7.1.0, 0.7.2.0
Change log	CHANGELOG.md
Dependencies	base (>=4.11.1 && <5), primitive (>=0.6.4) [details]
License	BSD-3-Clause
Copyright	2018 Andrew Martin
Author	Andrew Martin
Maintainer	andrew.thaddeus@gmail.com
Category	System
Home page	https://github.com/andrewthad/posix-api
Uploaded	by andrewthad at 2019-01-18T14:42:09Z

Modules

[Index] [Quick Jump]

Linux
- Linux.Socket
Posix
- Posix.Directory
- Posix.Socket

Downloads

posix-api-0.2.0.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

andrewthad, l3c_amartin

For package maintainers and hackage trustees

edit package information

Readme for posix-api-0.2.0.0

[back to package description]

posix-api

Objective

This library provides minimal bindings to system calls for POSIX-compliant operating systems. All functions follow these design decisions:

String is not used anywhere. ByteArray (from primitive) is used for serialized data. It is also used in certain filesystem function variants used in contexts where the paths are only ever handed over to other filesystem functions. Addr (from primitive) is used for pointers to data whose type is unknown. Ptr is used for pointers to data whose type is known.
Functions should not throw errors. This library uses IO (Either Errno a) in places where some libraries would use IO a.
The numeric types from Foreign.C.Types and System.Posix.Types are used in the type signatures of functions so that a haskell function's type signature matches its underlying POSIX equivalent exactly.
Flags are newtypes over CInt (or whatever integral type matches the posix specification) rather than enumerations. The data constructors are exported, making the types extensible for operating system that have additional flags.
There is some platform-specific code in this library. POSIX-specified data structures do not have the same in-memory representation on all platforms. Consequently, some of the code to serialize data to its C-struct representation must be written differently on different platforms. This is seldom needed. A viable alternative would be using the FFI to perform this serialization. However, the approach of using per-platform haskell code lets the serialization code inline better.

Pull requests that add bindings to POSIX APIs in a way that agrees with these guidelines will be accepted. Unfortunately, there is some grey area when it comes to what a "minimal binding" to a function is. Discussion may sometimes be necessary to refine the guidelines.

Build Instructions

This library relies on a currently-unreleased version of hsc2hs in order to build. In order to try out this library, try:

~/dev $ git clone https://github.com/haskell/hsc2hs
~/dev $ cd hsc2hs
~/dev/hsc2hs $ cabal install
~/dev/hsc2hs $ cd ..
~/dev $ git clone https://github.com/andrewthad/posix-api
~/dev $ cd posix-api
~/dev/posix-api $ cabal new-build --with-hsc2hs=~/.cabal/bin/hsc2hs

This will build posix-api with the unreleased version of the hsc2hs tool.

Infelicities

This project currently includes some Linux-specific code. It in the the Linux.Socket. The plan is to eventually move the Linux.Socket module into its own library. Currently, a ton of POSIX APIs are missing. These should be included.