getdns_context_set(3)

💖 getdns_context_set — bestie edition 💖

okay so this is the getdns manual page for getdns_context_set(3) — yes, the section-3 one, that's the library functions page, iykyk ✨

---

🌸 NAME 🌸

Bestie, this page is a whole girl group, not a solo act. Meet the lineup:

• getdns_context_set_append_name
• getdns_context_set_context_update_callback
• getdns_context_set_dns_root_servers
• getdns_context_set_dns_transport
• getdns_context_set_dnssec_trust_anchors
• getdns_context_set_dnssec_allowed_skew
• getdns_context_set_follow_redirects
• getdns_context_set_limit_outstanding_queries
• getdns_context_set_namespaces
• getdns_context_set_resolution_type
• getdns_context_set_suffix
• getdns_context_set_timeout

…and collectively they are the getdns context manipulation routines 🎀 periodt.

---

📚 LIBRARY 📚

DNS Resolver library — that's libgetdns, and you link it with -lgetdns 🫶

---

✨ SYNOPSIS ✨

First things first, include the header or nothing works, bestie:

#include <getdns.h>

Then here's the whole squad, exactly as they're declared:

getdns_return_t
getdns_context_set_append_name (getdns_context_t context,
   getdns_append_name_t when_to_append)

getdns_return_t
getdns_context_set_context_update_callback (getdns_context_t context,
   (*callback)(struct getdns_context *context, uint16_t changed_item))

getdns_return_t
getdns_context_set_dns_root_servers (getdns_context_t context,
   getdns_list *root_addresses)

getdns_return_t
getdns_context_set_dns_transport (getdns_context_t context,
   uint16_t transport)

getdns_return_t
getdns_contet_set_dnssec_allowed_skew (getdns_context *context,
   uint32_t skew_seconds)

getdns_return_t
getdns_contet_set_dnssec_trust_anchors (getdns_context *context,
   getdns_list *trust_anchors)

getdns_return_t
getdns_context_set_follow_redirects (getdns_context_t context,
   getdns_redirects_t followredir)

getdns_return_t
getdns_context_set_limit_outstanding_queries (getdns_context_t context,
   uint16_t limit)

getdns_return_t
getdns_context_set_namespaces (getdns_context_t context,
   size_t namespace_count,
   uint16_t *namespaces)

getdns_return_t
getdns_context_set_resolution_type (getdns_context_t context,
   uint16_t restype)

getdns_return_t
getdns_context_set_suffix (getdns_context *context,
   getdns_list *suffixes)

getdns_return_t
getdns_context_set_timeout (getdns_context_t context,
   uint16_t timeout)

ngl, notice that two of these are spelled getdns_contet_... in the synopsis (getdns_contet_set_dnssec_allowed_skew and getdns_contet_set_dnssec_trust_anchors) while the NAME section says getdns_context_set_dnssec_allowed_skew and getdns_context_set_dnssec_trust_anchors. I am not touching that. Copy-paste responsibly 💅

---

🦋 DESCRIPTION 🦋

So these functions are how you mess with an already-allocated-and-initialized context. Like, the context has to exist first. Go read getdns_context (3) for the tea on how to allocate, initialize and destroy contexts, and for the full deep-dive on what a getdns_context even is. 🧚

Here's the rundown on each one, no cap:

getdns_context_set_append_name — tells the API whether to slap a suffix onto the query string before it starts resolving a name. The suffix comes from getdns_context_set_suffix (3). 💖

getdns_context_set_context_update_callback — sets a function that gets called when there are changes to the system files (for example /etc/resolv.conf and /etc/hosts). 🎀

getdns_context_set_dns_transport — picks the transport used for DNS lookups. The default? UDP, and it falls back to TCP as needed. main character energy 🔥

getdns_context_set_dnssec_trust_anchors — lets you, the caller, specify trust anchors as alternatives to the default trust anchors. 👑

getdns_context_set_dnssec_allowed_skew — sets how many seconds of skew are allowed in either direction when checking an RRSIG's expiration and inception fields. Default is 0. ⭐

getdns_context_set_limit_outstanding_queries — the maximum number of outstanding DNS queries. Over that limit? The API queues your queries until current ones get answered, then it automatically fires off the queued ones. slay 🦋

getdns_context_set_dns_root_servers — hands over an alternate set of addresses to use for looking up the top level domains. Don't call it and you get the default: the list of IANA root servers (think of this as the root hints). 🌈

getdns_context_set_follow_redirects — whether DNS queries follow redirects (CNAME and DNAME). Default behavior is to follow redirects and return the eventual target. 🙈

getdns_context_set_namespaces — sets the namespaces the resolver uses. Default is DNS and then local files. Future implementations will support netbios, mdns, and nis. 💜

getdns_context_set_resolution_type — specifies whether DNS queries get performed with non-recursive lookups or as a stub resolver. ✨

getdns_context_set_suffix — appends suffixes to domain names prior to executing the lookup, based on getdns_context_set_append_name. 🍓

getdns_context_set_timeout — the number of milliseconds the API will wait for a response. 💀 (yes, milliseconds, not seconds, don't do that to yourself)

---

🎀 the parameters, one by one 🎀

• context — a previously allocated and initialized getdns_context. Like I said. Allocate first. 🫶
• callback — a callback function that will be called when changes are made to the system files (/etc/resolv.conf and /etc/hosts) for contexts created with set_from_os = 1. When this function is called, the changed_item parameter indicates which item in the context has changed. 🌸
• root_addresses — a list of getdns_dict types, each identifying a single root server to use to look up top level domains. Every dictionary includes two names: address_type, a bindata containing the string "IPv4" or "IPv6", and address_data, a bindata containing the IP address. 💅
• transport — may be one of:
  • GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP
  • GETDNS_CONTEXT_UDP_ONLY
  • GETDNS_CONTEXT_TCP_ONLY
  • GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN

If you need more information on what each of these means, reread the mnemonic and take a guess ;) — that's a direct quote from the source, and honestly? iconic.

• followredir — set it to GETDNS_REDIRECTS_FOLLOW (the default) and the eventual target of the redirect is returned. Set it to GETDNS_REDIRECTS_DO_NOT_FOLLOW and you get the CNAME or DNAME returned, and NOT the eventual target. 🦋
• limit — the maximum number of concurrent outstanding (unanswered) DNS queries. If exceeded, the API queues queries and issues them as the number of outstanding queries drops. A value of 0 indicates that there is no limit. ✨
• namespaces — the namespaces array holds an ordered list of namespaces that will be queried.

Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other functions.

The values are GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMESPACE_NIS.

When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS. 😭

• restype — can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_STUB (requires that forwarders be specified by the caller). 👑
• seconds_skew — the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields. ⭐
• suffixes — a list of bindatas that are strings that are to be appended based on getdns_context_set_append_name. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels. 🧚
• timeout — the number of milliseconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error. ⏰
• trust_anchors — list of bindatas that are the DNSSEC trust anchors expressed as RDATA from the DNSKEY resource records. The default are supplied by the IANA root. 💜
• when_to_append — the value is:
  1. GETDNS_APPEND_NAME_ALWAYS,
  2. GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
  3. GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or
  4. GETDNS_APPEND_NAME_NEVER.

---

🔥 RETURN VALUES 🔥

Upon successful completion the functions return GETDNS_RETURN_GOOD. Otherwise, the following error values are returned:

• GETDNS_RETURN_BAD_CONTEXT — if the context pointer is invalid. 💀
• GETDNS_RETURN_CONTEXT_UPDATE_FAIL — if there was a problem updating the context. 😭

---

🍓 EXAMPLES 🍓

TBD

(the source really does just say TBD, bestie. we wait. 💅)

---

🌈 FILES 🌈

• /etc/hosts
• /etc/resolv.conf

---

👑 SEE ALSO 👑

libgetdns(3), getdns_address(3), getdns_address_sync(3), getdns_context(3), getdns_general(3), getdns_general_sync(3), getdns_hostname(3), getdns_hostname_sync(3), getdns_service(3), getdns_service_sync(3).

---

and that's the whole page, bestie 🫶 go forth and set your context. this was getdns 1.7.3, dated December 2015 — yes, december 2015, she's vintage, she's still serving, and she's still in your man pages. 💖✨