Skip to main content

48  net standard library

The net module provides POSIX socket wrappers for TCP and UDP communication on Linux systems. The submodule net/http provides HTTP protocol parsing, header manipulation, and response generation.

#use io
#use net
#use net/http

48.1 Socket operations

Socket helpers return recoverable Conn (< Int | String >) ramifications rather than poisonous abort errors.

#use io
#use net

// Create a listening TCP socket on port 8080
listener = net::tcp_listen(8080, 128)
listener
   | fd =>
      io::out(("Listening on fd", fd))
   | err =>
      io::err(("Listen error:", err))
Function Signature Description
net::parse_ipv4 String => < Int | > Strictly parses dotted-quad IPv4 ("a.b.c.d") into a 32-bit network-order integer
net::tcp_listen Int, Int => Conn Creates and binds listening TCP socket on IPv4 port (0.0.0.0)
net::create_listener String, Int, Int => Conn Creates listening TCP socket bound to ip:port with SO_REUSEADDR, SO_REUSEPORT, and TCP_NODELAY
net::ensure_port_free String, Int => < | String > Probes IPv4, wildcard, and IPv6 without SO_REUSEPORT to verify ip:port is not already bound
net::tcp_accept Int => Conn Accepts client connection: < client_fd | error >
net::tcp_connect String, Int => Conn Connects to remote IPv4 host and port
net::tcp_connect_name String, Int => Conn Connects via DNS name lookup using getaddrinfo
net::send_str Int, String => Int Sends string bytes over socket
net::recv Int, Int => Chunk Reads up to max bytes into Chunk (< String | >)
net::close_fd Int => Int Closes socket descriptor (returns 0 on success, -1 on error)
net::set_nonblocking Int, <> => Int Sets non-blocking socket mode (O_NONBLOCK when <+>, blocking when <->)
net::set_nodelay Int, <> => Int Disables (<+>) or enables (<->) Nagle’s algorithm (TCP_NODELAY)
net::peer_addr Int => String Returns remote peer address IP:port formatted string
net::local_addr Int => String Returns local bound address IP:port formatted string
net::sendfile Int, Int, Int, Int => Int Linux sendfile(2): net::sendfile(out_fd, in_fd, offset, count) copies file bytes from offset to out_fd in the kernel; returns bytes sent, 0 at EOF, or -1 with errno set (-1 on non-Linux)

48.2 HTTP protocol support (net/http)

The net/http submodule parses HTTP/1.1 requests and formats responses:

#use io
#use net/http

req = "GET /index.html?v=1 HTTP/1.1\r\nHost: localhost\r\n\r\n"
path = http::path_of(req) // "/index.html"

// Construct standard HTTP response with pre-formatted headers:
body = "Hello, World!"
headers = http::header("Content-Type", "text/plain") +
          http::header("Content-Length", str::from_int(?body))
res = http::response(200, headers, body)
  • http::path_of(req: String) => String: Extracts the normalized request target path.
  • http::reason_of(code: Int) => String: Maps status code (e.g. 200, 404) to reason phrase ("OK", "Not Found").
  • http::header(name: String, value: String) => String: Generates Name: Value\r\n line.
  • http::response(status: Int, headers: String, body: String) => String: Constructs complete HTTP message: status line, headers, blank line separator, and body.
  • http::respond(fd: Int, status: Int, content_type: String, body: String) => Int: Formats standard Content-Type and Content-Length headers and writes complete response to client socket; returns total bytes written.