net_listen(3)

💖 hey bestie, meet net_listen 💖

okay so you're looking at the net_listen(3) page from the Arcan Lua API, and it's literally the moment a frameserver goes into networking server mode. no cap, this one's a whole vibe. 🫶

---

✨ NAME ✨

net_listen — Setup a network frameserver in listening mode 💅

---

🌈 SYNOPSIS 🌈

vid
net_listen( function:callback )
net_listen( string:name, function:callback )
net_listen( string:name, string:interface, function:callback )
net_listen( string:name, string:interface, int:port, function:callback )

---

🎀 DESCRIPTION 🎀

So you're launching a new frameserver in networking server mode, bestie. The callback argument behaves just like any other client connected through target_alloc, launch_avfeed and so on. The key difference from target_alloc is that clients are only allowed to connect through whatever protocol the network frameserver exposes — typically a12. 👑

The longer form accepts a name that has the same ([a-Z0-9_]1,30) restriction as normal connection points. It will not be allocated in the domain socket namespace, and the name is only used to limit the set of accepted keys from the keystore that are allowed to authenticate against the keystore. okay so it's giving "name tag that also does auth gatekeeping" energy. 🎀

Listening interface and port are implementation defined by default, but the long form with host and port can be used to override this. ✨

New clients are bootstrapped as 'handover' segments and thus need to be acknowledged via the use of accept_target. See the example further below, bestie — it's right there waiting for you. 🦋

By using target_input(vid, "num:secret") immediately on the returned vid, an extended authentication key can be set. This requires both a key authenticated for use with name and the right secret for a connection to be let through. no shortcuts, periodt. 🔥

If num is set to > 0 a limited number of unknown keys authenticated with the shared secret will be added to the list of known and accepted keys for name in the keystore. This opens a short window where man-in-the-middle attacks against unknown keys could be used (assuming the shared secret can be retrieved). The idea is to help bootstrap in controlled network environments or where there is an established secure side-band communication where the secret can be shared. 💀

⚠️ real-talk caveat: that short man-in-the-middle window is a real thing in the page, so don't treat it like a cute little loophole — it's for controlled network environments or established secure side-band communication where the secret can be shared. 🙈

---

💅 NOTES 💅

1. terminating the listening vid will not immediately terminate any clients that have been authenticated and given a handover segments, but no new clients will be accepted. 🫶
2. — the original page has a bare 2 here with no text attached, so bestie, we are absolutely not inventing anything. not me staring at a blank note 😭

---

🍓 EXAMPLE 🍓

function net_listen0()
      net_listen(
      function(source, status)
            if status.kind == "segment_request" then
                  accept_target(
                        function(source, status)
                              if status.kind == "terminated" then
                                    delete_image(source)
                              else
                                    print("client", source, status.kind)
                              end
                        end
                  )
            end
            if status.kind == "terminated" then
                  shutdown(EXIT_SUCCESS)
            end
      end)
end

---

mwah 💋 — this little page comes from the network source/version, dated October 2026, and yup, you just read net_listen(3) 🫶✨