qlibs:(dnsstub)

📦 version 31, in alpine 3.24

🌈 dns — stub resolver 🌈 (the qlibs:(dnsstub) page)

okay bestie, this is the stub resolver page, and it's giving very specific Unix energy. Let's get into it 💅

💖 NAME 💖

dns — stub resolver. That's the whole name section, periodt.

🧚 SYNTAX 🧚

#include "dnsresolv.h"

int dns_resolvconfip(char servers[512],uint32 scope[32]);

int dns_transmit_start(struct dns_transmit *q,const char servers[512],
    int flagrecursive,const char *q,const char qtype[2],
    const char localip[16]);
int dns_transmit_start6(struct dns_transmit *q,const char servers[512],
    int flagrecursive,const char *q,const char qtype[2],
    const char localip[16],const uint32 scopes[32]);

int dns_sortip4(char *servers,unsigned int n);
int dns_sortip6(char *servers,unsigned int n);

✨ DESCRIPTION ✨

So dns_resolvconfip reads the name servers defined in /etc/resolv.conf and uses ip6_ifscan to fetch their IPv4/IPv6 addresses together with the scope for the LLU address. Up to 32 name servers can be specified. iconic 💫

Apart from the system-wide /etc/resolv.conf, the IP addresses of name servers can — preferably — be provided by means of the environment variable $DNSCACHEIP for each user application. The variable $DNSCACHEIP may include up to 32 name server IP addresses separated by white spaces:

DNSCACHEIP="10.0.1.53 fe80::1%lo0 ::1"

dns_transmit_start and dns_transmit_start6 use the list of name server IPs for a recursive or non-recursive query q of type qtype starting from IP address localip, for which the struct dns_transmit provides the required bookkeeping information. dns_transmit_start6 additionally is able to evaluate the given scope_id as information for the local interface in order to bind to the remote IPv6 LLU addresses. Usually scope_id defaults to 0. 🫶

dns_sortip4 and dns_sortip6 randomize the list of name server IPs upon call, and as a result the first address is used to facilitate the name lookup. FQDN. 👑

💀 RETURN CODES 💀

Different from the original djb implementation, the following return-code scheme is used:

  • rc > 0 — a "positive" answer is given, thus results returned.
  • rc = 0 — a "neutral" answer was provided, thus typically the operation succeeded, but without replies.
  • rc < 0 — an operational error was encountered.

Potentially, this needs to be treated specifically:

  • DNS_INT (rc = -4) — internal DNS operational error; i.e. resources were not available.
  • DNS_COM (rc = -3) — DNS communication error.
  • DNS_ERR (rc = -2) — parsing errors and others.
  • DNS_MEM (rc = -1) — memory error occured.

A "safe" usage of return codes thus checks not only the presence of a return code, but rather additionally its sign. Negative return codes point to errors. Do not skip the sign check, bestie — that's the whole vibe check. 😭

🦋 SEE ALSO 🦋

That's the whole page, bestie 🫶 — source/version: qlibs:(dnsstub), and the footer didn't give me a date to mention. 💜

📦 where this page comes from