unix_sockets(3tcl)

💖 unix_sockets — the Tcl girlies' guide to Unix Domain Sockets 💖

okay so bestie, this is unix_sockets(3tcl), aka Unix Domain Sockets for Tcl, and honestly? it's giving local-only IPC excellence. no cap.

---

✨ NAME ✨

unix_sockets — communicate using unix domain sockets 🦋

---

✨ SYNOPSIS ✨

package require unix_sockets ?0.7?

unix_sockets::listen path accept_handler
unix_sockets::connect path

---

✨ DESCRIPTION ✨

so like. Unix domain sockets are a filesystem based IPC mechanism — think of them as IP sockets' cool younger sibling — except the plot twist is that they can only be used by processes on the same system. same machine only, bestie, it's an exclusive little club 💅. this package is just a wrapper so you can use them from your Tcl scripts, and honestly it ate.

the channels these commands hand back support all the standard Tcl channel operations: read, puts, gets, flush, close, chan configure, chan event, etc. all of it. iconic behavior, no notes. 🌈

🎧 unix_sockets::listen path accept_handler

open a listening socket at path. and listen — if path already exists, it gets unlinked first (yes, it just deletes it, that's the vibe, so don't be weird about it). you must have permission to create path in its parent directory, so like, check your permissions before you come crying to me 😭. when a client connects, accept_handler is invoked, with the channel handle of the new client connection appended to it. returns the channel handle of the listening socket. 🫶

🎧 unix_sockets::connect path

connect as a client to the unix domain socket at path. returns the channel handle for the new connection. simple. slay. ⭐

---

✨ EXAMPLES ✨

🍓 the server (echo girlie)

a simple server that echoes back to the client the first line it sends, then closes the socket:

proc readable con {
    set msg [gets $con]
    puts $con $msg
    close $con
}

proc accept con {
    chan event $con readable [list readable $con]
}

set listen [unix_sockets::listen /tmp/example.socket accept]

vwait ::forever

it literally serves. and then it closes the con. periodt.

🍓 the client

a client that opens a socket, writes a line to it, waits for a response and exits:

proc readable con {
    set msg [gets $con]
    puts "got response: ($msg)"
    set ::done 1
}

set con [unix_sockets::connect /tmp/example.socket]
puts $con "hello, world"
flush $con
chan event $con readable [list readable $con]
vwait ::done

the flush $con is doing the lord's work btw, don't skip it 🙈

---

✨ SEE ALSO ✨

close(3tcl), chan(3tcl), socket(3tcl), read(3tcl), puts(3tcl), eof(3tcl), fblocked(3tcl), flush(3tcl)

go read those too, bestie, they're the supporting cast and they all understood the assignment 💜

---

✨ KEYWORDS ✨

socket, channel, unix, ipc

---

✨ LICENSE ✨

this package is placed in the public domain by Cyan Ogilvie. public domain!! literally free!! we love a generous king 👑✨

---

fr fr, version 0.7 of unix_sockets(3tcl) — that's the version in the synopsis up top and it's also the version down here at the bottom, same number, no drama, we're consistent. mwah 💖 🎀 🧚 🌸