`(sigil socket)`

(sigil socket) - Network Socket Library

TCP and UDP socket operations for network programming. Supports both blocking and non-blocking I/O for use with coroutines and event loops.

TCP Client

(import (sigil socket))

(let ((sock (tcp-connect "example.com" 80)))
  (socket-write-line sock "GET / HTTP/1.0")
  (socket-write-line sock "")
  (display (socket-read-all sock))
  (socket-close sock))

TCP Server

(let ((server (tcp-listen 8080)))
  (let loop ()
    (let ((client (tcp-accept server)))
      (socket-write-line client "Hello!")
      (socket-close client)
      (loop))))

UDP

(let ((sock (udp-socket)))
  (udp-send sock "127.0.0.1" 5000 "Hello")
  (socket-close sock))

Exports

socket?procedure

Check if a value is a socket object.

(socket? (tcp-connect "localhost" 80))  ; => #t
(socket? "not a socket")                ; => #f

tcp-connectprocedure

Connect to a TCP server.

Returns a socket on success, or #f on failure.

(tcp-connect "example.com" 80)  ; => #<socket>

tcp-listenprocedure

Create a listening TCP server socket.

Binds to the specified port and begins listening for connections.

(tcp-listen 8080)  ; => #<socket>

tcp-acceptprocedure

Accept an incoming connection on a listening socket.

Blocks until a client connects. Returns a new socket for communicating with the client.

(let ((client (tcp-accept server)))
  (socket-write-line client "Hello!"))

udp-socketprocedure

Create a UDP socket.

(udp-socket)  ; => #<socket>

udp-bindprocedure

Bind a UDP socket to a local port.

(udp-bind sock 5000)

udp-sendprocedure

Send data via UDP to a host and port.

(udp-send sock "127.0.0.1" 5000 "Hello")

udp-receiveprocedure

Receive data from a UDP socket.

Returns a list (data host port) or #f on error.

socket-closeprocedure

Close a socket.

(socket-close sock)

socket-closed?procedure

Check if a socket has been closed.

(socket-closed? sock)  ; => #t or #f

socket-readprocedure

Read data from a socket.

Returns a string, empty string (no data in non-blocking mode), or eof-object when connection is closed.

socket-read-bytevectorprocedure

Read raw bytes from a socket into a bytevector.

Unlike socket-read (which returns a UTF-8 string), this preserves raw bytes without any encoding interpretation. Essential for binary protocols and file downloads.

Returns a bytevector, empty bytevector (no data in non-blocking mode), or eof-object when connection is closed.

socket-read-lineprocedure

Read a line from a socket (up to newline).

socket-writeprocedure

Write data to a socket.

Returns the number of bytes written, or #f on error.

socket-write-lineprocedure

Write a line to a socket (appends newline).

socket-set-non-blocking!procedure

Set a socket to non-blocking mode.

(socket-set-non-blocking! sock #t)

socket-non-blocking?procedure

Check if a socket is in non-blocking mode.

socket-ready?procedure

Check if a socket has data ready to read.

Returns #t if data is available without blocking.

socket-selectprocedure

Wait for activity on multiple sockets.

Returns a list of sockets that are ready.

socket-set-tcp-nodelay!procedure

Disable Nagle's algorithm for lower latency.

(socket-set-tcp-nodelay! sock #t)

gethostnameprocedure

Get the local hostname.

(gethostname)  ; => "my-computer"

resolve-hostnameprocedure

Resolve a hostname to an IP address.

(resolve-hostname "localhost")  ; => "127.0.0.1"

socket-local-addressprocedure

Get the local address and port of a socket.

Returns (host . port).

socket-remote-addressprocedure

Get the remote address and port of a connected socket.

Returns (host . port).

unix-connectprocedure

Connect to a Unix domain socket.

Returns a socket on success, or #f on failure. Not available on Windows.

(unix-connect "/var/run/docker.sock")  ; => #<socket>

unix-listenprocedure

Create a listening Unix domain socket.

Binds to the specified path and begins listening for connections. Removes any stale socket file at the path before binding. Use tcp-accept to accept incoming connections. Not available on Windows.

(unix-listen "/tmp/my-server.sock")  ; => #<socket>

call-with-tcp-connectionprocedure

Connect to a TCP server, call proc with the socket, then close it.

Ensures the socket is closed even if an error occurs.

(call-with-tcp-connection "example.com" 80
  (lambda (sock)
    (socket-write-line sock "GET / HTTP/1.0")
    (socket-read-all sock)))

call-with-tcp-serverprocedure

Create a TCP server, call proc with the listening socket, then close it.

Useful for one-shot server scenarios or tests.

(call-with-tcp-server 8080
  (lambda (server)
    (let ((client (tcp-accept server)))
      (socket-write-line client "Hello!")
      (socket-close client))))

socket-send-allprocedure

Send all data to a socket, retrying on partial writes.

Returns #t on success, #f on failure.

(socket-send-all sock "Hello, world!")  ; => #t

socket-read-allprocedure

Read all available data from a socket until EOF.

Returns the accumulated string, or #f on error.

(socket-read-all sock)  ; => "HTTP/1.0 200 OK\r\n..."

make-line-readerprocedure

Create a buffered line reader for a socket.

Returns a procedure that reads complete lines from the socket, buffering partial lines internally. Useful for line-based protocols where data may arrive in fragments.

(define read-line (make-line-reader sock))
(read-line)  ; => "hello" or #f if no complete line yet
(read-line)  ; => "world"

%tcp-connect-syncvariable

(No description)

%tcp-connect-ipvariable

(No description)

%tcp-connect-ip-timeoutvariable

(No description)

%tcp-connect-ip-timeout-statusvariable

(No description)

fd-selectvariable

(No description)

socket-fdvariable

(No description)

%resolve-hostname-syncvariable

(No description)

%resolve-startvariable

(No description)

%resolve-takevariable

(No description)

%resolve-cancelvariable

(No description)