← Index

x/sys/socket

Blocking IPv4 TCP on the Socket class, over libc FFI.

First consumer: x/logo/serve.x (whose Darwin-only constants this replaces). Recv truncates at the first NUL byte (ptr->str) – fine for text protocols; recv-bytes is the lossless byte-list door (#374).

Class Socket

Blocking IPv4 TCP over libc FFI: listen/accept on the server side, connect on the client side, send/recv/close on both.

No DNS: hosts are dotted quads (“127.0.0.1”). Failures raise tag ‘io Errs with errno detail; recv answers nil at orderly EOF (absence, not a sentinel).

(Socket tcp-listen port . backlog)

Create a TCP server socket: socket + SO_REUSEADDR + bind(INADDR_ANY, port) + listen.

Parameters:

• port : INT — Port to bind
• backlog : INT — Listen backlog; default 16

Returns: INT — The listening file descriptor

(Socket accept fd)

Block until a client connects; the peer address is discarded (stat the fd’s peer later if wanted).

Parameters:

• fd : INT — Listening file descriptor

Returns: INT — The connected client file descriptor

(Socket tcp-connect host port)

Open a TCP connection to host:port (no DNS – dotted quads only).

Parameters:

• host : STRING — Dotted-quad IPv4 address
• port : INT — Port to connect to

Returns: INT — The connected file descriptor

(Socket send fd s)

Send the whole string; raises on failure.

Parameters:

• fd : INT — Connected file descriptor
• s : STRING — Bytes to send

Returns: INT — Bytes sent

(Socket recv fd maxlen)

Receive up to maxlen bytes as a string; nil at orderly EOF (the peer closed); raises on failure.

Parameters:

• fd : INT — Connected file descriptor
• maxlen : INT — Maximum bytes to receive

Returns: ANY — The received string, or nil at EOF

(Socket resolve name)

The host’s first IPv4 address as a dotted quad, via getaddrinfo (#412) – the DNS door; every other Socket method still takes quads. Raises tag ‘io with the gai code when resolution fails, tag ‘value when the name has no IPv4 address.

Parameters:

• name : STRING — Hostname to resolve

Returns: STRING — A dotted quad, e.g. “140.82.114.3”

(Socket recv-bytes fd maxlen)

Receive up to maxlen bytes as a BYTE LIST – the lossless door (recv’s string return truncates at the first NUL; this one carries binary intact, #374); nil at orderly EOF; raises on failure.

Parameters:

• fd : INT — Connected file descriptor
• maxlen : INT — Maximum bytes to receive

Returns: ANY — Byte list (0-255 values), or nil at EOF

(Socket close fd)

Close a socket file descriptor.

Parameters:

• fd : INT — File descriptor to close

Returns: ANY — nil

(Socket local-port fd)

The local port fd is bound to – the one the kernel chose when the bind asked for port 0. TCP and UDP alike.

Parameters:

• fd : INT — A bound or listening file descriptor

Returns: INT — The bound port, host order

(Socket udp-bind port)

Create a UDP socket bound to port on all interfaces – the receiving end. Read with (Socket recv-from fd n) for sender identity, or plain (Socket recv) when it does not matter.

Parameters:

• port : INT — Port to bind (INADDR_ANY)

Returns: INT — The bound datagram file descriptor

(Socket udp-connect host port)

Create a CONNECTED UDP socket: the peer address is fixed once, and the plain (Socket send)/(Socket recv) pair then works datagram-wise – the request/reply shape. For unconnected sends use (Socket send-to).

Parameters:

• host : STRING — Dotted-quad IPv4 address
• port : INT — Destination port

Returns: INT — The connected datagram file descriptor

(Socket send-to fd s host port)

Send one datagram to host:port through an unconnected UDP socket.

Parameters:

• fd : INT — Datagram file descriptor
• s : STRING — Bytes to send (one datagram)
• host : STRING — Dotted-quad IPv4 destination
• port : INT — Destination port

Returns: INT — Bytes sent

(Socket recv-from fd maxlen)

Block for one datagram; return it WITH the sender’s identity. Like recv, the payload string truncates at the first NUL byte (ptr->str) – fine for text protocols.

Parameters:

• fd : INT — Bound datagram file descriptor
• maxlen : INT — Maximum bytes to receive

Returns: PAIR — (payload . (host . port))

(Socket %sockaddr-un path)

Build a malloc’d sockaddr_un for path – the caller frees. Raises tag ‘value past 99 bytes (the struct’s path field is 104).

Parameters:

• path : STRING — Filesystem socket path (under 100 bytes)

Returns: PTR — The packed address (110 bytes)

(Socket unix-listen path . backlog)

Create a unix-domain stream server socket at path: socket + bind + listen. The path must not already exist (bind refuses) – unlink a stale one first; accept/send/recv/close are shared with TCP.

Parameters:

• path : STRING — Filesystem socket path to create
• backlog : INT — Listen backlog; default 16

Returns: INT — The listening file descriptor

(Socket unix-connect path)

Open a unix-domain stream connection to the socket at path.

Parameters:

• path : STRING — Filesystem socket path to connect to

Returns: INT — The connected file descriptor