dnsjit.output.dnscli(3)

💅 dnsjit.output.dnscli — the manual page, bestie edition

ok so you found dnsjit.output.dnscli(3), part of the dnsjit Library Functions Manual, and honestly? she's a DNS aware UDP/TCP/TLS client. iconic. let's get into it 🎀

---

✨ NAME ✨

dnsjit.output.dnscli — a DNS aware UDP/TCP/TLS client. that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

first, grab her:

  local dnscli = require("dnsjit.output.dnscli")

🌸 UDP Receiver Chain

  local output = dnscli.new(dnscli.UDP)
  output:connect("127.0.0.1", "53")
  input:receiver(output)

🌸 TCP Nonblocking

  local output = dnscli.new(dnscli.TCP + dnscli.NONBLOCKING)
  output:send(object)

---

✨ DESCRIPTION ✨

okay so here's the tea ☕ this DNS client can send either a core.object.dns or a core.object.payload object, and she can do it two ways: through the receiver interface, or by calling send(). either way it goes out as a DNS query, and then you can get the response back through the producer interface. main character behavior fr.

now, here's the part you actually need to know 👇

• if the object you're sending is a core.object.dns, she's gonna peek at the includes_dnslen attribute, and depending on which protocol you're on, she will either disregard it, include it, or send the DNS length as an extra packet.
• if the object you're sending is a core.object.payload, no special handling, no drama — it gets sent exactly as is. periodt. 💅

and when responses come in? the producer interface generates core.object.payload objects, which may include the DNS length depending on the protocol used — and you, the caller, have to handle that. no one's doing it for you, bestie. 🫶

---

✨ MODES ✨

these transport modes and options are what you got when you're creating a new Dnscli output. pick your fighter:

• UDP — create an output using UDP. 🍓
• TCP — create an output using TCP.
• TLS — create an output using TCP and encrypt it with TLS. 🔥
• NONBLOCKING — make the client nonblocking. go look at send() and produce() for the details, iykyk. 🌈

---

✨ Functions ✨

• Dnscli.new(mode) — create a new Dnscli output. your origin story. ⭐
• Dnscli:timeout(seconds, nanoseconds) — set (or return) the timeout used for sending and reciving. ⚠️ must be used before connect(), no exceptions, don't test her.
• Dnscli:connect(host, port) — connect to the host and port, and returns 0 if it worked. slay. 💖
• Dnscli:nonblocking() — returns whether nonblocking mode is on (true) or off (false). a little vibe check, if you will.
• Dnscli:send(object, sent) — send an object, and optionally keep sending after sent bytes. unlike the receive interface, this one actually tells you if the send worked or not, which you might really need on nonblocking connections. returns -2 on error, -1 if it was interrupted, timed out, or couldn't send because of nonblocking, or the number of bytes sent. 🫣 note: the counters for sent, received, errors and timeouts are not affected by this function. she's not counting this one, bestie.
• Dnscli:receive() — return the C functions and context for receiving objects; these objects will be sent.
• Dnscli:produce() — return the C functions and context for producing objects; these objects are received. if nonblocking mode is enabled, the producer returns a payload object with length zero if there was nothing to receive. if nonblocking mode is disabled, the producer waits for data, and if it times out (see timeout) it returns a payload object with length zero. on error, the producer returns nil. 😭
• Dnscli:packets() — return the number of "packets" sent — which is actually the number of completely sent payloads. 💀
• Dnscli:received() — return the number of "packets" received — which is actually the number of successful calls to recvfrom(2) that returned data.
• Dnscli:errors() — return the number of errors when sending or receiving.
• Dnscli:timeouts() — return the number of timeouts when sending or receiving.

---

✨ SEE ALSO ✨

core.object.dns(3), core.object.payload(3), core.timespec(3)

go read those too, they're part of the friend group 🌸

---

✨ AUTHORS and CONTRIBUTORS ✨

the legends responsible for this whole thing 👑

• Jerry Lundström (DNS-OARC)
• Tomáš Křížek (CZ.NIC)
• Petr Špaček (ISC)

maintained by DNS-OARC 🫶

       https://www.dns-oarc.net/

---

✨ BUGS ✨

found something broken? want a feature? okay so for issues and feature requests, please use:

       https://codeberg.org/DNS-OARC/dnsjit/issues

got a question, or just need a hand? for questions and help, please use:

       admin@dns-oarc.net

---

ngl, reading a whole manpage is a lot. but you did it. 💜

anyway, that's the page — brought to you by dnsjit version 1.5.1, and this little dnsjit.output.dnscli(3) corner of the Library Functions Manual. no cap, you're gonna be so good at this. bye bestie, go send some queries ✨🎀💅