UDNS: DNS Resolver Library

Quick links


UDNS is a stub DNS resolver library with ability to perform both syncronous and asyncronous DNS queries.

Easy to use and asyncronous DNS resolver is a problem for a very long time. Standard libresolv from Berkeley Internet Name Daemon (BIND) distribution, included in most Unix-like operating systems, is good for syncronous A (AAAA) and PTR lookups. Other DNS Resource Record (RR) types (such as MX, TXT and so on) requires parsing of raw DNS packets at the application level, which isn't a trivial task and requires good knowlege of DNS protocols and packet structure. While it is possible to add such interfaces to use for other RR types to standard resolv library, it's main problem remains: it is not asyncronous. Most applications that requires asyncronous DNS processing either implements their own resolver modules (which, again, is not a trivial task, and sometimes leads to incompatibilities with other resolver libraries and bugs which are difficult to find), or uses forked-resolver model, where separate process is forked just to perform DNS queries, which requires quite some resources, especially when an application already have some sort of event loop in place to multiplex I/O. Asyncronous DNS resolver is a must for many nowadays applications, such as GUI (GUI-application should not stop processing user interface events while performing DNS queries), high-performance servers (such as mail servers) using event-loop model (see for example an excellent "The C10K problem" page at kegel.com describing various methods to handle many client requests in parallel).

There are at least two good async resolver libraries -- adns by Ian Jackson, and c-ares by Daniel Stenberg and others (derived from ares library written by Greg Hudson at MIT). Both libraries are asyncronous by design, and have good and bad sides:

This library, libudns, tries to solve at least some of the above problems. The goals for it, in no particular order, are:

Asyncronous interface works with so-called "callback" routines -- an application submits any number of various queries to the library (queried to one or more resolver contexts), each supplied with (it's own) pointer to application-defined routine which will be called by the library when the query completes (either successefully or not). Similar approach is used in adns and c-ares libraries. Callback routine receives pointer to original query structure (which may be freed or reused for other queries), resulting data if query completes successefully or error code in case of error. The library have core "DNS Query Dispatch" routines which should be called from within main application event loop, which may be traditional select/poll-based or custom callback-based one.

In addition, library provides tradition syncronous interface (like gethostbyname() or getaddrinfo()), when library routine does not return until the query completes. Such syncronous interface may be mixed together with asyncronous interface in the same program or thread.

Please note the library is a stub resolver, it is aimed at client programs that uses nearby recursive resolver such as BIND or dnscache from djbdns package or similar. It plays the same role as standard stub resolver from libresolv, and it requires reqursive DNS server.


Complete manual page for the library is available here in html format for online reference. Usage examples will be provided here in some future, when I will find a time for this, or when someone will contribute good examples ;)


As of version 0.0.5, the library is released in terms of GNU Lesser General Public License (LGPL) which can be found on GNU site and inside the source tarball which is available here.

Current stable version of the library is 0.5 (released 9 Mar 2024), source available here, recent user-visible changes here.

See also NOTES file and a TODO.

Thanks to Christian Praehauser, Windows port of the package can be obtained here.


The library is being written by Michael Tokarev, <mjt+udns@corpit.ru>

Page last modified (except of version changes) at Fri, 08 Apr 2005 20:55:00 +0400 by mjt.

Return to my software page.