Tcl Library Source Code

Bounty program for improvements to Tcl and certain Tcl packages.

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]


dns - Tcl Domain Name Service Client

Table Of Contents


package require Tcl 8.2
package require dns ?1.5.0?

::dns::resolve query ?options?
::dns::configure ?options?
::dns::name token
::dns::address token
::dns::cname token
::dns::result token
::dns::status token
::dns::error token
::dns::reset token
::dns::wait token
::dns::cleanup token


The dns package provides a Tcl only Domain Name Service client. You should refer to (1) and (2) for information about the DNS protocol or read resolver(3) to find out how the C library resolves domain names. The intention of this package is to insulate Tcl scripts from problems with using the system library resolver for slow name servers. It may or may not be of practical use. Internet name resolution is a complex business and DNS is only one part of the resolver. You may find you are supposed to be using hosts files, NIS or WINS to name a few other systems. This package is not a substitute for the C library resolver - it does however implement name resolution over DNS. The package also extends the package uri to support DNS URIs (4) of the form or dns://my.nameserver/ The dns::resolve command can handle DNS URIs or simple domain names as a query.

Note: The package defaults to using DNS over TCP connections. If you wish to use UDP you will need to have the tcludp package installed and have a version that correctly handles binary data (> 1.0.4). This is available at If the udp package is present then UDP will be used by default.

Note: The package supports DNS over TLS (RFC 7858) for enhanced privacy of DNS queries. Using this feature requires the TLS package.



% set tok [dns::resolve]
% dns::status $tok
% dns::address $tok
% dns::name $tok
% dns::cleanup $tok

Using DNS URIs as queries:

% set tok [dns::resolve ";type=MX"]
% set tok [dns::resolve "dns://"]

Reverse address lookup:

% set tok [dns::resolve]
% dns::name $tok
% dns::cleanup $tok

Using DNS over TLS (RFC 7858):

% set tok [dns::resolve -nameserver  -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt]
% dns::wait $tok
% dns::address $tok


  1. Mockapetris, P., "Domain Names - Concepts and Facilities", RFC 1034, November 1987. (

  2. Mockapetris, P., "Domain Names - Implementation and Specification", RFC 1035, November 1087. (

  3. Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", RFC 1886, December 1995. (

  4. Josefsson, S., "Domain Name System Uniform Resource Identifiers", Internet-Draft, October 2003, (

  5. Gulbrandsen, A., Vixie, P. and Esibov, L., "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000, (

  6. Ohta, M. "Incremental Zone Transfer in DNS", RFC 1995, August 1996, (

  7. Hu, Z., etc al. "Specification for DNS over Transport Layer Security (TLS)", RFC 7858, May 2016, (


Pat Thoyts

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category dns of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.




DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886, rfc 7858




Copyright © 2002, Pat Thoyts