Module `net/unix`

net/unix

Stability: unstable — may still change; see below.

Unix domain sockets — UnixListener / UnixStream (plans/archive/STD_API_AUDIT.md §7 P0 item 10: the sys layer was fully plumbed with no typed wrapper). The API mirrors TcpListener/TcpStream one-to-one, with a filesystem Path where TCP has a SocketAddr.

The LISTENER's socket file is NOT removed on close — like Rust, the caller unlinks it (fs_dir.remove_file); binding to a path that already exists throws AddressInUse.

Every network operation is an io.async future on the single event-loop thread, and kernel failures throw IoExn carrying a NetError (D1) rather than resolving to a negative count.

Stability

unstable — it mirrors std/net/tcp one-to-one deliberately, which means it also inherits that module's open shapes: no pointer-free read (safe code needs std/io/bufio's BufReader or the Reader defaults), and no incoming, which waits on an async iterator protocol. Two things are specific to this module and not yet decided: a stream cannot report the peer path Rust's UnixStream::peer_addr gives, even though the pieces exist one layer down (std/sys/sockinfo.getpeername plus std/sys/unix.sockaddr_un_path) — so the shape of a Unix address in this API is still unchosen; and there is no UnixDatagram beside the stream pair. Freezing follows the tcp decisions plus an address accessor.

Types

UnixListener object

UnixListener

A Unix-domain socket listening on a filesystem path.

Fields

Name	Type	Description
`_fd`	i32
`_path`	String
`_is_closed`	bool

impl(UnixListener, ...)

bind : (UnixListener) fn(path : Path, io : Io) -> Impl(Future(UnixListener, IoExn))

Bind to a filesystem path and start listening. The path must not already exist (AddressInUse otherwise) and is NOT unlinked on close.

Parameters

Name	Type	Notes
`path`	Path
`io`	Io

Returns: Impl(Future(UnixListener, IoExn))

accept : (UnixListener) fn(self : UnixListener, io : Io) -> Impl(Future(UnixStream, IoExn))

Accept an incoming connection, returning a new UnixStream.

Parameters

Name	Type	Notes
`self`	UnixListener
`io`	Io

Returns: Impl(Future(UnixStream, IoExn))

local_path : (UnixListener) fn(self : UnixListener) -> String

The filesystem path this listener is bound to.

Parameters

Name	Type	Notes
`self`	UnixListener

Returns: String

close : (UnixListener) fn(self : UnixListener, io : Io) -> Impl(Future(unit, IoExn))

Close the listener socket (the socket FILE stays — unlink it yourself).

Parameters

Name	Type	Notes
`self`	UnixListener
`io`	Io

Returns: Impl(Future(unit, IoExn))

fd : (UnixListener) fn(self : UnixListener) -> i32

Get the underlying file descriptor.

Parameters

Name	Type	Notes
`self`	UnixListener

Returns: i32

UnixStream object

UnixStream

A connected Unix-domain stream socket.

Fields

Name	Type	Description
`_fd`	i32
`_is_closed`	bool

Trait Implementations

IoTraits

impl(UnixStream, ...)

connect : (UnixStream) fn(path : Path, io : Io) -> Impl(Future(UnixStream, IoExn))

Connect to a Unix-domain socket at path, returning a new stream.

Parameters

Name	Type	Notes
`path`	Path
`io`	Io

Returns: Impl(Future(UnixStream, IoExn))

read : (UnixStream) fn(self : UnixStream, buf : *(u8), size : usize, io : Io) -> Impl(Future(usize, IoExn))

Read up to size bytes into buf, resolving to the number actually read. 0 — and only 0 — means the peer closed; a SHORT count is ordinary on a stream socket and is not end-of-stream, so a caller that needs size bytes loops. Awaiting parks this task on the event loop until the kernel has bytes; a failure throws IoExn. The raw pointer needs pragma(Pragma.AllowUnsafe) — safe code uses the Reader defaults (read_to_end, read_to_string) or BufReader(UnixStream).