nish:net
Non-blocking sockets for a program that owns its loop: TCP, UDP, Unix-domain sockets, and a level-triggered readiness loop to wait on them.
import {
NET_LISTEN_RING,
NET_SO_KEEPALIVE,
NET_SO_RCVBUF,
NET_SO_SNDBUF,
NET_TCP_NODELAY,
NET_TCP_QUICKACK,
NET_UNIX_SEQPACKET,
NET_UNIX_STREAM,
NET_UNIX_UNLINK_STALE,
connectResult,
netAddress,
netClose,
netLocalPort,
netMss,
netRead,
netRingState,
netSetOption,
netShutdown,
netWrite,
netWrite2,
peerCredentials,
pollAdd,
pollCreate,
pollModify,
pollRemove,
pollWait,
recvFd,
sendFd,
tcpAccept,
tcpConnect,
tcpListen,
tcpListenFlags,
udpBind,
udpRecvFrom,
udpSendTo,
unixAccept,
unixConnect,
unixListen,
unixListenMode,
unixSocketPair,
} from "nish:net";
import { netAddress, tcpListen, tcpAccept, netRead, netWrite, pollCreate, pollAdd, pollWait } from "nish:net";
const server = tcpListen("::", 8080, 128);
const loop = pollCreate();
pollAdd(loop, server, 1, 1);
const ready: i32[] = new Array<i32>(32);
const peer: u8[] = new Array<u8>(18);
const n = pollWait(loop, ready, -1);
const conn = tcpAccept(server, peer); // -11 when none is waiting
connectResult
How a connection tcpConnect started went, asked once fd is writable.
netAddress
Write the address form of a numeric host and a port.
netClose
Close the descriptor.
netLocalPort
The port the socket is bound to, which is how a program that listened on port 0 learns the one the kernel chose.
netMss
The maximum segment size a connected TCP socket sends, the payload bytes one segment carries, so that one write can fill whole segments: Linux's TCP_INFO tcpi_snd_mss, or TCP_MAXSEG where that is not above 0 and on Darwin.
netRead
Read at most len bytes into buf[off, off + len).
netRingState
Whether NET_LISTEN_RING listeners accept into rings.
netSetOption
Set one socket option from a whitelist.
netShutdown
Shut one side of a connection, or both.
netWrite
Write at most len bytes of buf[off, off + len).
netWrite2
Write a[aOff, aOff + aLen) and then b[bOff, bOff + bLen) in one system call (sendmsg with two iovecs), so a header and a body leave together with no copy into one buffer.
peerCredentials
The process at the other end of a connected Unix socket, as the kernel recorded it when the connection was made (the connect, or the socketpair), not who holds the other end now: a peer that has changed its uid since, passed the socket on, or closed, still reads as it was.
pollAdd
Watch fd and report it under token.
pollCreate
A readiness loop: a descriptor, close-on-exec, that watches others, level-triggered.
pollModify
New events or a new token for a descriptor the loop watches.
pollRemove
Stop watching fd.
pollWait
Wait until a watched descriptor is ready or the timeout passes, and write one pair per ready descriptor: ready[2k] its token and ready[2k + 1] its events, 1 readable and 2 writable, with 4 added for a hang-up or an error.
recvFd
Read at most len bytes into buf[off, off + len) from the Unix socket sock, with the first descriptor that came with them.
sendFd
Send buf[off, off + len) over the Unix socket sock, with one copy of the descriptor fd riding on them (SCM_RIGHTS).
tcpAccept
The next waiting connection, as a descriptor of its own, non-blocking and close-on-exec.
tcpConnect
A new TCP socket, non-blocking and close-on-exec, that starts connecting to addr and is answered at once, while the connection is still being made: the EINPROGRESS (-115) of a non-blocking connect is not a failure.
tcpListen
A listening TCP socket on a numeric host, with SO_REUSEADDR, so a restarted server rebinds a port its old connections still hold in TIME_WAIT.
tcpListenFlags
tcpListen's socket, with flags.
udpBind
A datagram socket, non-blocking and close-on-exec, bound to a numeric host and port as tcpListen's is, "::" and its IPv4 fallback included.
udpRecvFrom
Receive the next datagram into buf[off, off + len), cut to len if it is longer, in one recvmsg.
udpSendTo
Send buf[off, off + len) to to in one sendmsg.
unixAccept
The next waiting connection on a Unix listener, non-blocking and close-on-exec.
unixConnect
A new socket, non-blocking and close-on-exec, connected to the listener at path.
unixListen
A listening Unix-domain stream socket at path, whose file is 0600, so only its owner may connect.
unixListenMode
unixListen's socket with the file's mode chosen, set between the bind and the listen, so no connect gets in under a wider one.
unixSocketPair
Two sockets already connected to each other, non-blocking and close-on-exec: a channel without a name, for a child process or for one side of a program.
Every socket is non-blocking and close-on-exec, so a call that would wait
answers -11 and a child that spawnSync starts inherits none of them.
Each export is the global of the same name, renamed. Every call answers an
i32: >= 0 is success and a negative number is the failure's errno,
negated, with Linux's numbers on every platform for the codes a loop
branches on (-11 would block, -95 unsupported, -32 the peer has gone,
-104 reset, -98 in use, -111 refused, -110 timed out, -88 not a
socket, -22 a bad argument); any other failure is the host's -errno. No
call touches the arena.
A wasm32 target and the wasi profile have no sockets, so the checker
refuses every call there with NL2404, except netMss, which compiles to
-1. No call may be made in a scope() task or a parallel body. Under Node
every call throws, because a socket is ready only to Node's event loop,
which a program that owns its loop never returns to; the option ids and the
NET_UNIX_ constants still read as numbers. No call resolves a name:
nish/net/dns does that on the program's own loop.
The address form
An address is 18 bytes of a u8[]: the 16 bytes of
an IPv6 address, with IPv4 written as the mapped ::ffff:a.b.c.d, then the
port, big-endian. One form for both families, in memory the caller owns, so
a server that accepts a million connections allocates nothing to learn who
they are from. An array longer than 18 bytes is fine; the rest is not
touched. An address array shorter than 18 bytes is -22, not a panic.
Bounds
Every off/len range is checked in the compiled code before
the call, as dst.set(src, at) checks its range, and a range outside the
array panics with slice out of range, exit 1.
Level-triggered
A descriptor still ready when the program waits again is reported again, so a loop that handles one ready pair of several, or leaves a datagram unread, loses nothing.
Functions
connectResult
How a connection tcpConnect started went, asked once fd is writable.
The kernel clears the failure as it is read, so a second call answers
0; close the descriptor with netClose either way.
const connectResult: (fd: i32) => i32
fdi32requiredThe descriptor tcpConnect answered.
returnsi32
0 when the connection is made, or its failure from SO_ERROR,
such as -111 for a port nobody listens on and -110 for one that
never answered.
netAddress
Write the address form of a numeric host and a port. No call looks a name
up; nish/net/dns resolves one first.
const netAddress: (
out: u8[],
host: string,
port: i32,
) => i32
outu8[]requiredThe array the 18 bytes are written into; one shorter than 18 bytes is left as it was.
hoststringrequiredAn IPv4 dotted quad or an IPv6 literal.
porti32requiredThe port, 0..65535.
returnsi32
0, or -22 for a name, a string with a NUL inside it, a port
outside 0..65535, or an out shorter than 18 bytes.
netClose
Close the descriptor. It is gone after the call whatever the answer, as
close(2) promises on Linux. Closing a descriptor also stops a loop
watching it. Not willreturn, because a socket the program inherited
with a linger time can wait.
const netClose: (fd: i32) => i32
fdi32requiredThe descriptor.
returnsi320, or the failure.
netLocalPort
The port the socket is bound to, which is how a program that listened on
port 0 learns the one the kernel chose.
const netLocalPort: (fd: i32) => i32
fdi32requiredA bound socket.
returnsi32The port, or the failure.
netMss
The maximum segment size a connected TCP socket sends, the payload bytes
one segment carries, so that one write can fill whole segments: Linux's
TCP_INFO tcpi_snd_mss, or TCP_MAXSEG where that is not above 0
and on Darwin. It never panics. The answer moves as the path does, so
read it when it is needed rather than once.
// A batch of whole segments, or the caller's own size where there is no MSS.
export const batch = (conn: i32, fallback: i32): i32 => {
const mss = netMss(conn);
return mss > 0 ? mss * 8 : fallback;
};
const netMss: (fd: i32) => i32
fdi32requiredA connected TCP socket.
returnsi32
The size, or a plain -1, never an errno, for anything else: a
descriptor that is not open, a socket with no peer (a listener, or one
never connected, though the kernel answers its default 536 for
those), a socket that is not TCP, a connection a NET_LISTEN_RING
listener accepted, whose ring cannot ask for it, and every call on
wasm, where it compiles to the constant with the descriptor still evaluated. It throws
under Node.
netRead
Read at most len bytes into buf[off, off + len). The range is checked.
const netRead: (
fd: i32,
buf: u8[],
off: i32,
len: i32,
) => i32
fdi32requiredA connected socket.
bufu8[]requiredThe array the bytes are written into.
offi32requiredThe first index written.
leni32required
The most bytes read; a len of 0 answers 0, so ask for at
least one byte.
returnsi32
The count, 0 at the end of the stream, -11 when nothing is
waiting, or the failure.
netRingState
Whether NET_LISTEN_RING listeners accept into rings.
const netRingState: () => i32
returnsi32
1 when they do, 0 until a listener has found rings or a
refusal, or the negative errno rings were refused with, in which case
they serve descriptors.
netSetOption
Set one socket option from a whitelist. There is no way to pass a raw level and option number, because that would be an untyped call into the kernel. Refused at compile time on wasm, and it throws under Node.
const netSetOption: (
fd: i32,
option: i32,
value: i32,
) => i32
fdi32requiredA socket.
optioni32requiredOne of the NET_* option ids.
valuei32required
0 or 1 for the switches, a byte count for the buffer
sizes.
returnsi32
0, or the failure: -9 for a closed descriptor, -88 for one
that is not a socket, -22 for any other option, and -95 for
NET_TCP_QUICKACK off Linux.
netShutdown
Shut one side of a connection, or both. On a connection a
NET_LISTEN_RING listener accepted, the shutdown goes behind the bytes
already written, so the peer reads them and then the end of the stream.
const netShutdown: (fd: i32, how: i32) => i32
fdi32requiredA connected socket.
howi32required0 the read side, 1 the write side, 2 both.
returnsi32
0, -22 for any other how, -9 for a closed ring
connection, or the failure.
netWrite
Write at most len bytes of buf[off, off + len). The range is checked.
A peer that has gone is -32, never SIGPIPE, so a closed connection
cannot end the process.
const netWrite: (
fd: i32,
buf: readonly u8[],
off: i32,
len: i32,
) => i32
fdi32requiredA connected socket.
bufreadonly u8[]requiredThe bytes; it may be readonly.
offi32requiredThe first index sent.
leni32requiredThe most bytes sent.
returnsi32
The count, which may be fewer than len, -11 when the send
buffer is full, -32 for a gone peer, or the failure.
netWrite2
Write a[aOff, aOff + aLen) and then b[bOff, bOff + bLen) in one system
call (sendmsg with two iovecs), so a header and a body leave together
with no copy into one buffer. The program sends the rest of a short
write, as after netWrite. Both ranges are checked, a's first, and
either may be empty. A gone peer is -32, never SIGPIPE.
const netWrite2: (
fd: i32,
a: readonly u8[],
aOff: i32,
aLen: i32,
b: readonly u8[],
bOff: i32,
bLen: i32,
) => i32
fdi32requiredA connected socket.
areadonly u8[]requiredThe first bytes; it may be readonly.
aOffi32requiredThe first index of a sent.
aLeni32requiredThe bytes of a sent.
breadonly u8[]requiredThe second bytes; it may be readonly.
bOffi32requiredThe first index of b sent.
bLeni32requiredThe bytes of b sent.
returnsi32
The count of bytes taken, which may be fewer than aLen + bLen
and may end inside a, -11 when the send buffer is full, -32 for a
gone peer, or the failure.
peerCredentials
The process at the other end of a connected Unix socket, as the kernel
recorded it when the connection was made (the connect, or the
socketpair), not who holds the other end now: a peer that has changed
its uid since, passed the socket on, or closed, still reads as it was.
const peerCredentials: (fd: i32, out: i32[]) => i32
fdi32requiredA connected Unix socket, refused as sendFd's sock is.
outi32[]required
out[0], out[1], out[2] are written with the pid, uid and
gid. A uid or gid of 2^31 or above wraps into the i32 (-2 is uid
4294967294). On Darwin the pid is -1 where the SDK has no
LOCAL_PEERPID or the kernel refuses it.
returnsi32
0, -107 on every platform for a socket with no peer (a
listener, or one never connected), -22 for an out shorter than 3
before anything is asked, or the failure.
pollAdd
Watch fd and report it under token.
const pollAdd: (
loop: i32,
fd: i32,
events: i32,
token: i32,
) => i32
loopi32requiredThe loop.
fdi32requiredThe descriptor to watch.
eventsi32required1 readable, 2 writable, 3 both, 0 neither.
tokeni32required
An i32 of the program's choosing that comes back as it went
in.
returnsi32
0, -17 for a descriptor the loop already watches (on Darwin
it is left under the new token) or for a slot handle another loop
watches (a slot is in one loop at a time), or -22 for an event bit
past 2.
pollCreate
A readiness loop: a descriptor, close-on-exec, that watches others, level-triggered. Epoll on Linux; kqueue on Darwin, from whose filters the runtime builds epoll's answers.
const pollCreate: () => i32
returnsi32The loop's descriptor, or the failure.
pollModify
New events or a new token for a descriptor the loop watches.
const pollModify: (
loop: i32,
fd: i32,
events: i32,
token: i32,
) => i32
loopi32requiredThe loop.
fdi32requiredThe watched descriptor.
eventsi32required1 readable, 2 writable, 3 both, 0 neither.
tokeni32requiredThe token it is reported under from now on.
returnsi320, or -2 for a descriptor the loop does not watch.
pollRemove
Stop watching fd. Closing a descriptor stops the watching too.
const pollRemove: (loop: i32, fd: i32) => i32
loopi32requiredThe loop.
fdi32requiredThe watched descriptor.
returnsi320, or -2 for a descriptor the loop does not watch.
pollWait
Wait until a watched descriptor is ready or the timeout passes, and write
one pair per ready descriptor: ready[2k] its token and ready[2k + 1]
its events, 1 readable and 2 writable, with 4 added for a hang-up or
an error. A signal that interrupts the wait answers 0, as a timeout
does, until the process opens a NET_LISTEN_RING listener with rings:
from then on, for the rest of its life, the wait goes on to its deadline, and signalFd() is how a loop sees a signal. Not
willreturn, because it can wait forever. Nothing allocates,
and ready is never written past its length.
const pollWait: (
loop: i32,
ready: i32[],
timeoutMs: i32,
) => i32
loopi32requiredThe loop.
readyi32[]requiredThe array the pairs are written into.
timeoutMsi32requiredThe most milliseconds to wait; any negative number waits forever.
returnsi32
The count of pairs, at most ready.length / 2 and at most 64
(the rest are still ready at the next wait), 0 on a timeout, or -22
for a ready shorter than 2.
recvFd
Read at most len bytes into buf[off, off + len) from the Unix socket
sock, with the first descriptor that came with them. Every further
descriptor in the message is closed before the answer, and room is made
for 8, so the kernel drops the rest of a message that carries more and
the bytes are still answered. The descriptor kept is close-on-exec and is
not made non-blocking: its status flags are the open file's, which the
sender shares, so set what the program needs before it joins a loop. The
range is checked.
const recvFd: (
sock: i32,
buf: u8[],
off: i32,
len: i32,
fd: i32[],
) => i32
socki32requiredA connected Unix socket, refused as sendFd's is.
bufu8[]requiredThe array the bytes are written into.
offi32requiredThe first index written.
leni32requiredThe most bytes read.
fdi32[]required
fd[0] is written with the descriptor, or -1 when the message
carried none.
returnsi32
The count, 0 at the end of the stream, -11 when nothing is
waiting, -22 for a len of 0 or an empty fd before anything is
read, or the failure.
sendFd
Send buf[off, off + len) over the Unix socket sock, with one copy of
the descriptor fd riding on them (SCM_RIGHTS). The receiver's
recvFd gets a new descriptor for the same open file, offset and status
flags shared, as dup gives; fd stays open here. On a stream socket
the count can be short of len: the descriptor has travelled with the
first bytes, so send the rest with netWrite, not sendFd, or the
receiver gets a second copy. The range is checked.
const sendFd: (
sock: i32,
fd: i32,
buf: readonly u8[],
off: i32,
len: i32,
) => i32
socki32requiredA connected Unix socket.
fdi32requiredThe descriptor to send.
bufreadonly u8[]requiredThe bytes the descriptor rides on; it may be readonly.
offi32requiredThe first index sent.
leni32requiredThe bytes sent; at least one, because a descriptor travels with data.
returnsi32
The bytes sent, or the failure: -22 for a len of 0 or a
negative fd; -9 for an fd that is not open or a closed sock;
-88 for a sock that is not a socket; -95 for a socket of another
family; -32 for a gone peer, never SIGPIPE.
tcpAccept
The next waiting connection, as a descriptor of its own, non-blocking and
close-on-exec. Not willreturn: on a blocking socket the program
inherited, it waits.
const tcpAccept: (fd: i32, peer: u8[]) => i32
fdi32requiredThe listener.
peeru8[]requiredThe array the peer's address form is written into.
returnsi32
The connection's descriptor (a slot handle from a
NET_LISTEN_RING listener, whose peer is written as zeros), -11
when none is waiting, -23 when a ring listener's slots are all
taken, -22 for a peer shorter than 18 bytes before anything is
accepted (so no connection is taken and lost), or -95 for a
datagram socket. A ring listener whose accept found memory short
answers -12 or -105 once, pauses for a back-off (10 ms, doubling
to 640 ms while it recurs) and accepts again. Any other errno but
-11, -4, -103 or -71 stops it accepting and is answered from
then on; close it and listen again.
tcpConnect
A new TCP socket, non-blocking and close-on-exec, that starts connecting
to addr and is answered at once, while the connection is still being
made: the EINPROGRESS (-115) of a non-blocking connect is not a
failure.
Watch the descriptor for writability, then ask connectResult. It holds
TCP_NODELAY, so a small write is sent at once. It does not wait and does
not allocate.
const tcpConnect: (addr: readonly u8[]) => i32
addrreadonly u8[]required
The address form; an IPv4 address connects from an IPv4
socket, any other from an IPv6 one. It may be readonly.
returnsi32
The descriptor; any other failure closes the socket and is
answered instead, and an addr shorter than 18 bytes is -22 before
any socket exists.
tcpListen
A listening TCP socket on a numeric host, with SO_REUSEADDR, so a
restarted server rebinds a port its old connections still hold in
TIME_WAIT. An IPv4 host is an IPv4 socket; any other is IPv6 with
IPV6_V6ONLY off, so "::" hears both families, and on a kernel without
IPv6 "::" is IPv4's 0.0.0.0.
const tcpListen: (
host: string,
port: i32,
backlog: i32,
) => i32
hoststringrequiredA numeric host.
porti32required
The port; 0 lets the kernel choose (read it with
netLocalPort).
backlogi32requiredThe length of the accept queue.
returnsi32
The listener's descriptor, -98 when the port is in use, or
-22 for a host that is not a literal.
tcpListenFlags
tcpListen's socket, with flags.
Flag 1 sets SO_REUSEPORT before the bind, so several listeners that all
ask for it share one port, each with its own accept queue, in one process
or several. On Linux they each get new connections, spread by a hash of
the 4-tuple, and only listeners of one user may share; on Darwin one of
them takes the connections, which buys a restart without a gap rather
than a spread. A port held by a listener without flag 1 is -98 to one
that asks for it, and the other way round.
Flag 2 sets TCP_NODELAY on every connection tcpAccept takes from the
listener, on every platform: the runtime sets it on each accepted socket
rather than trusting the kernel to copy it, and a connection on which it
cannot be set is closed and its failure answered.
Flag 4, with flag 1 and on Linux only, attaches a classic BPF program
(SO_ATTACH_REUSEPORT_CBPF) that hands each connection to the listener at
the index of the CPU that received it, in the order the group's listeners
were bound; a CPU past the group's size falls back to the hash.
Flag 8, NET_LISTEN_RING, accepts into io_uring slots on Linux: each
connection is a slot handle at or above 2^20 rather than a descriptor, so
a listener holds connections past RLIMIT_NOFILE. netRead, netWrite,
netWrite2, netClose, netLocalPort and the poll loop take a slot
handle; netSetOption answers -95, and calls that need a descriptor,
sendFd among them, answer -9.
The first listener that finds rings or a refusal decides for the process:
where the kernel refuses rings it serves descriptors, and netRingState
answers the errno. A listener whose rings fail for want of descriptors or
memory serves descriptors itself, and a later listener asks again. Off
Linux the flag is accepted and does nothing.
const tcpListenFlags: (
host: string,
port: i32,
backlog: i32,
flags: i32,
) => i32
hoststringrequiredA numeric host, as for tcpListen.
porti32requiredThe port.
backlogi32requiredThe length of the accept queue.
flagsi32required
The sum of the flags: 3 is both, 5 and 7 steer, 8
accepts into rings, and 0 is tcpListen exactly.
returnsi32
The listener's descriptor or the failure: -22 for any other
bit, a negative flags, or flag 4 without 1, before a socket is made;
-95 for flag 4 off Linux; -23 once the process has opened 31 ring
listeners, closed or not.
udpBind
A datagram socket, non-blocking and close-on-exec, bound to a numeric
host and port as tcpListen's is, "::" and its IPv4 fallback included.
The ECN bits of every datagram are always read.
const udpBind: (host: string, port: i32, flags: i32) => i32
hoststringrequiredA numeric host.
porti32requiredThe port.
flagsi32required
1 is SO_REUSEPORT, so several sockets that all ask for it
share a port and the kernel spreads the datagrams across them; 2 is
UDP_GRO, so the kernel may coalesce a flow's datagrams that arrive
after the bind into one receive (-95 on Darwin).
returnsi32
The descriptor, -22 for any other bit, -98 for a port in use
without flag 1, or the failure.
udpRecvFrom
Receive the next datagram into buf[off, off + len), cut to len if it
is longer, in one recvmsg. The range is checked. An empty datagram is a
datagram and answers 0. Not willreturn, as udpSendTo.
const udpRecvFrom: (
fd: i32,
buf: u8[],
off: i32,
len: i32,
from: u8[],
meta: i32[],
) => i32
fdi32requiredA datagram socket.
bufu8[]requiredThe array the payload is written into.
offi32requiredThe first index written.
leni32requiredThe most bytes taken.
fromu8[]required
The array the sender's address form is written into, ready to
pass to udpSendTo as a reply's to.
metai32[]required
Two numbers written: meta[0] the GRO segment size, the size
of each datagram the kernel coalesced into this one (0 when it
coalesced none; walk the buffer in steps of it, the last possibly
shorter), and meta[1] the ECN bits the datagram arrived with. Always
0, 0 on Darwin, where a meta[1] of 0 cannot say ECN is unsupported.
returnsi32
The datagram's length, -11 when none is waiting, or -22 for
a from shorter than 18 bytes or a meta shorter than 2, before
anything is taken.
udpSendTo
Send buf[off, off + len) to to in one sendmsg. The range is checked.
Not willreturn: on a blocking socket the program inherited, it waits.
An IPv4 socket sends to a mapped ::ffff:a.b.c.d address as IPv4.
const udpSendTo: (
fd: i32,
buf: readonly u8[],
off: i32,
len: i32,
to: readonly u8[],
segment: i32,
ecn: i32,
) => i32
fdi32requiredA datagram socket.
bufreadonly u8[]requiredThe payload; it may be readonly.
offi32requiredThe first index sent.
leni32requiredThe payload's length.
toreadonly u8[]requiredThe address form of the receiver; it may be readonly.
segmenti32required
Above 0, GSO: the kernel cuts the payload into datagrams
of segment bytes, the last one shorter, so one call sends many; 0
sends one datagram. 0..65535; above 0 is -95 on Darwin.
ecni32required
The two ECN bits of the IP header: 0 not ECN-capable, 1
ECT(1), 2 ECT(0), 3 CE. Above 0 is -95 on Darwin.
returnsi32
The bytes sent, -11 when the send buffer is full, or -22 for
a to shorter than 18 bytes, a segment outside 0..65535, an ecn
outside 0..3, or a payload the kernel will not cut (more segments than
it takes in one call, or a segment the route cannot carry).
unixAccept
The next waiting connection on a Unix listener, non-blocking and close-on-exec. No peer address is written: a Unix client is seldom bound.
const unixAccept: (fd: i32) => i32
fdi32requiredThe listener.
returnsi32
The connection's descriptor, -11 when none is waiting, or the
failure.
unixConnect
A new socket, non-blocking and close-on-exec, connected to the listener
at path. A connect needs write permission on the file and search
permission on every directory above it.
const unixConnect: (path: string) => i32
pathstringrequiredAs for unixListen.
returnsi32
The descriptor; -111 when nothing listens there; -2 when
there is no such file; -11 on Linux and -111 on Darwin when the
listener's backlog is full (the socket is closed; try again later); or
the path refusals unixListen has.
unixListen
A listening Unix-domain stream socket at path, whose file is 0600, so
only its owner may connect. A bind never replaces a file. Closing the
listener does not unlink its file: unlinkSync it when the server stops,
or let the next start's NET_UNIX_UNLINK_STALE clear it. A call that
fails after its bind closes the socket and unlinks the file it made.
const unixListen: (
path: string,
backlog: i32,
flags: i32,
) => i32
pathstringrequired
Bytes up to the first NUL, at most 107 bytes on Linux and 103
on Darwin, relative to the working directory. A leading @ names
Linux's abstract namespace, which leaves no file (-95 on Darwin).
backlogi32requiredThe length of the accept queue.
flagsi32required
0, or NET_UNIX_UNLINK_STALE to clear a socket file
nothing listens on, found by a probe connect, and bind again.
returnsi32
The listener's descriptor or the failure: -98 when the path
exists (a live listener stays -98); -17 when the flag finds
something that is not a socket; -95 on Darwin when the flag finds a
socket file, which it cannot probe; -36 for a path too long; -22 for
an empty path, a bare @, a NUL inside, or any other flag bit.
unixListenMode
unixListen's socket with the file's mode chosen, set between the bind
and the listen, so no connect gets in under a wider one.
const unixListenMode: (
path: string,
backlog: i32,
flags: i32,
mode: i32,
) => i32
pathstringrequiredAs for unixListen.
backlogi32requiredThe length of the accept queue.
flagsi32requiredAs for unixListen.
modei32required0 to 0o777, and no other bits.
returnsi32
The listener's descriptor, unixListen's failures, or -22 for
a mode outside that range or an abstract name, which has no file to
give a mode to.
unixSocketPair
Two sockets already connected to each other, non-blocking and close-on-exec: a channel without a name, for a child process or for one side of a program.
const unixSocketPair: (kind: i32, fds: i32[]) => i32
kindi32required
NET_UNIX_STREAM (1), a byte stream, or
NET_UNIX_SEQPACKET (2), where each write is one message and a read
returns one message, never two run together; 2 is -95 on Darwin.
fdsi32[]required
The array the two descriptors are written into, as fds[0]
and fds[1].
returnsi32
0, or -22 for any other kind or an fds shorter than 2,
before a socket exists.
Constants
NET_LISTEN_RING
NET_LISTEN_RING: i32
tcpListenFlags flag 8: accept into io_uring slots instead of descriptors.
NET_SO_KEEPALIVE
NET_SO_KEEPALIVE: i32
SO_KEEPALIVE, option id 3: value 1 probes an idle connection, 0 does not.
NET_SO_RCVBUF
NET_SO_RCVBUF: i32
SO_RCVBUF, option id 5: the receive buffer, value in bytes; Linux doubles the value it stores.
NET_SO_SNDBUF
NET_SO_SNDBUF: i32
SO_SNDBUF, option id 4: the send buffer, value in bytes; Linux doubles the value it stores.
NET_TCP_NODELAY
NET_TCP_NODELAY: i32
TCP_NODELAY, option id 1: value 1 sends a small write at once, 0 lets Nagle batch it.
NET_TCP_QUICKACK
NET_TCP_QUICKACK: i32
TCP_QUICKACK, option id 2 (Linux; -95 elsewhere): value 1 acknowledges at once, 0
delays. Linux does not keep quick-ACK mode: the kernel leaves it on its own,
so a server that wants a mode sets it again after every response.
// After each response: Linux may have left quick-ACK mode.
export const answered = (conn: i32): i32 => netSetOption(conn, NET_TCP_QUICKACK, 1);
NET_UNIX_SEQPACKET
NET_UNIX_SEQPACKET: i32
unixSocketPair kind: each write one message (SOCK_SEQPACKET).
NET_UNIX_STREAM
NET_UNIX_STREAM: i32
unixSocketPair kind: a byte stream.
NET_UNIX_UNLINK_STALE
NET_UNIX_UNLINK_STALE: i32
unixListen flag 1: unlink a socket file nothing listens on, then bind.

