---
name: "dnsjit.output.dnscli"
section: "3"
platform: "linux"
package: "dnsjit"
version: "1.5.0-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/dnsjit.output.dnscli"
---

# dnsjit.output.dnscli(3)

DNS aware UDP/TCP/TLS client

## NAME

dnsjit.output.dnscli - DNS aware UDP/TCP/TLS client

## SYNOPSIS

  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

The DNS client can a *core.object.dns* or a *core.object.payload* object via the receiver interface or using *send()* and send it as DNS query after which it can receive the response by using the producer interface. If the object being sent is a *core.object.dns* then it will look at *includes\_dnslen* attribute and depending on the protocol it will disregard, include or send the DNS length as an extra packet. If the object being sent is a *core.object.payload* then no special handling will be done and it will be sent as is. When receiving responses the producer interface will generate *core.object.payload* objects which may include the DNS length depending on the protocol used and must be handled by the caller.

### MODES

These transport modes and options are available when creating a new Dnscli output.

- 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, see *send()* and *produce()*.

### Functions

- **Dnscli.new**(mode)

  Create a new Dnscli output.

- **Dnscli:timeout**(seconds, nanoseconds)

  Set or return the timeout used for sending and reciving, must be used before *connect()*.

- **Dnscli:connect**(host, port)

  Connect to the *host* and *port* and return 0 if successful.

- **Dnscli:nonblocking**()

  Return if nonblocking mode is on (true) or off (false).

- **Dnscli:send**(object, sent)

  Send an object and optionally continue sending after *sent* bytes. Unlike the receive interface this function lets you know if the sending was successful or not which might be needed on nonblocking connections. Returns -2 on error, -1 if interrupted, timed out or unable to send due to nonblocking, or the number of bytes sent. **Note** the counters for sent, received, errors and timeouts are not affected by this function.

- **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 will return a payload object with length zero if there was nothing to receive. If nonblocking mode is disabled the producer will wait for data and if timed out (see *timeout*) it will return a payload object with length zero. The producer returns nil on error.

- **Dnscli:packets**()

  Return the number of "packets" sent, actually the number of completely sent payloads.

- **Dnscli:received**()

  Return the number of "packets" received, actually the number of successful calls to [*recvfrom*(2)](/recvfrom/2.md) 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)

## AUTHORS and CONTRIBUTORS

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

Maintained by DNS-OARC

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

## BUGS

For issues and feature requests please use:

*https://github.com/DNS-OARC/dnsjit/issues*

For question and help please use:

*admin@dns-oarc.net*