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) 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