D. J. Bernstein
Internet publication
djbdns

The dns library interface

These are DNS client library routines. They are meant to be used in browsers and other programs that resolve domain names. There is a separate blurb explaining advantages of this library over the libresolv library.

Host name to IP addresses

     #include <dns.h>

     dns_ip4(&out,&fqdn);
     dns_ip4_packet(&out,buf,len);

     stralloc out = {0};
     stralloc fqdn = {0};
     char *buf;
     unsigned int len;

dns_ip4 looks up 4-byte IP addresses for the fully-qualified domain name in fqdn. It puts the concatenation of the IP addresses into out and returns 0. If the domain does not exist in DNS, or has no IP addresses, out will be empty.

If dns_ip4 has trouble with the DNS lookup or runs out of memory, it returns -1, setting errno appropriately. It may or may not change out.

If fqdn is a dotted-decimal IP address, dns_ip4 puts that IP address into out without checking DNS. More generally, if fqdn is a dot-separated sequence of dotted-decimal IP addresses, dns_ip4 puts those IP addresses into out without checking DNS. Brackets may appear inside the dotted-decimal IP addresses; they are ignored.

dns_ip4_packet is a low-level component of dns_ip4, designed to support asynchronous DNS lookups. It reads a DNS packet of length len from buf, extracts IP addresses from the answer section of the packet, puts the addresses into out, and returns 0 or -1 the same way as dns_ip4.

Qualification

     #include <dns.h>

     dns_ip4_qualify(&out,&fqdn,&udn);

     stralloc out = {0};
     stralloc fqdn = {0};
     stralloc udn = {0};

dns_ip4_qualify feeds the name udn through qualification and looks up 4-byte IP addresses for the result. It puts the fully qualified domain name into fqdn, puts the concatenation of the IP addresses into out, and returns 0. If the domain does not exist in DNS, or has no IP addresses, out will be empty.

If dns_ip4_qualify has trouble with the qualification, has trouble with DNS, or runs out of memory, it returns -1, setting errno appropriately. It may or may not change out and fqdn.

IP address to host name

     #include <dns.h>

     dns_name4(&out,ip);
     dns_name_packet(&out,buf,len);
     dns_name4_domain(q,ip);

     stralloc out = {0};
     char ip[4];
     char q[DNS_NAME4_DOMAIN];
     char *buf;
     unsigned int len;

dns_name4 looks up the domain name for the 4-byte IP address in ip. It puts the (first) domain name into out and returns 0. If the relevant in-addr.arpa domain does not exist in DNS, or has no PTR records, out will be empty.

If dns_name4 has trouble with the DNS lookup or runs out of memory, it returns -1, setting errno appropriately. It may or may not change out.

dns_name_packet is a low-level component of dns_name4, designed to support asynchronous DNS lookups. It reads a DNS packet of length len from buf, extracts the first PTR record from the answer section of the packet, puts the result into out, and returns 0 or -1 the same way as dns_name4.

dns_name4_domain is another low-level component of dns_name4. It converts an IP address such as 1.2.3.4 into a domain name such as 4.3.2.1.in-addr.arpa and places the packet-encoded domain name into q.

MX records

     #include <dns.h>

     dns_mx(&out,&fqdn);
     dns_mx_packet(&out,buf,len);

     stralloc out = {0};
     stralloc fqdn = {0};
     char *buf;
     unsigned int len;

dns_mx looks up MX records for the fully-qualified domain name in fqdn. It puts the MX records into out and returns 0. Each MX record is a two-byte MX distance followed by a \0-terminated dot-encoded domain name. If the domain does not exist in DNS, or has no MX records, out will be empty.

If dns_mx has trouble with the DNS lookup or runs out of memory, it returns -1, setting errno appropriately. It may or may not change out.

dns_mx_packet is a low-level component of dns_mx, designed to support asynchronous DNS lookups. It reads a DNS packet of length len from buf, extracts the MX records from the answer section of the packet, puts the results into out, and returns 0 or -1 the same way as dns_mx.

TXT records

     #include <dns.h>

     dns_txt(&out,&fqdn);
     dns_txt_packet(&out,buf,len);

     stralloc out = {0};
     stralloc fqdn = {0};
     char *buf;
     unsigned int len;

dns_txt looks up TXT records for the fully-qualified domain name in fqdn. It puts the concatenation of the TXT records into out and returns 0. If the domain does not exist in DNS, or has no TXT records, out will be empty.

If dns_txt has trouble with the DNS lookup or runs out of memory, it returns -1, setting errno appropriately. It may or may not change out.

dns_txt_packet is a low-level component of dns_txt, designed to support asynchronous DNS lookups. It reads a DNS packet of length len from buf, extracts the TXT records from the answer section of the packet, puts the results into out, and returns 0 or -1 the same way as dns_txt.