getdns_context(3)

🌸 getdns_context — the manual page 💅

okay bestie, so this is the getdns_context(3) page from the getdns crew, and honestly? it's giving "foundation of everything". no cap. let's get into it 🫶

---

✨ NAME ✨

getdns_context, getdns_context_create, getdns_context_create_with_memory_functions, getdns_context_create_with_extended_memory_functions, getdns_context_destroy, getdns_context_get_api_information — the getdns context create and destroy routines. the whole "make a context, yeet a context" situation 🎀

📚 LIBRARY 📚

DNS Resolver library (libgetdns, -lgetdns)

---

✨ SYNOPSIS ✨

#include <getdns.h>

getdns_return_t
getdns_context_create (getdns_context ** context,
   int set_from_os)

getdns_return_t
getdns_context_create_with_memory_functions (getdns_context ** context,
   int set_from_os,
   void *(*malloc) (size_t),
   void *(*realloc) (void *, size_t),
   void (*free) (void *))

getdns_return_t
getdns_context_create_with_extended_memory_functions     (getdns_context
**context,
   int set_from_os,
   void *userarg,
   void *(*malloc) (void *userarg, size_t),
   void *(*realloc) (void *userarg, void *, size_t),
   void (*free) (void *userarg, void *))

void
getdns_context_destroy (getdns_context *context)

getdns_dict *
getdns_context_get_api_information (getdns_context *context)

---

💖 DESCRIPTION 💖

so like. every single call to a getdns function needs a DNS context, which is basically a lil group of API settings that decide how your DNS calls go down. for most apps? a default context is literally all you need, periodt.

to make a brand new DNS context, you use:

getdns_return_t   getdns_context_create  (getdns_context_t  *context,
bool set_from_os)

the call to getdns_context_create comes back immediately with a context you can already use with other API calls, and that context is carrying the API's default values. most apps are gonna want set_from_os set to true, fr fr.

to clean everything up — including all the outstanding transactions that were called using this context — you use:

void getdns_context_destroy (getdns_context_t context)

when getdns_context_destroy() returns, the app knows that every outstanding transaction tied to this context will have been called. and any callbacks that hadn't been called before getdns_context_destroy() got called? they get called with a callback_type of GETDNS_CALLBACK_CANCEL. getdns_context_destroy() only returns after all the needed cleanup is done and the callbacks are made. so it's thorough. it's a closer. 💅

okay now here's the spicy part: if you're using getdns in a multi-threaded manner, then you're of course using the underlying OpenSSL library multi-threaded too, and the version of that library in use might have requirements on this issue. you may need to provide one or two functions to let it function properly. for example, before you call getdns_context_create() you may need to use the openssl functions CRYPTO_set_id_callback and CRYPTO_set_locking_callback to set up asynchronous operation (the application calls these functions once for initialisation). Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.

• context — used to return the pointer to an opaque structure. the caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function. the result is a newly allocated and initialized context (if there are no errors). in the getdns_destroy_context function, this is the context whose associated memory will be released.
• set_from_os — if set_from_os is 0 then the caller must provide forwarding name servers if running in stub mode. if set_from_os is 1 then the system files are used to initialize the context. /etc/resolv.conf is used to populate forwarders when running as a stub resolver (only "nameserver" lines are recognized). if set_from_os is 1, /etc/hosts entries are preferred before resorting to a DNS query. errors in the system files will not prevent the context from being constructed. 🦋
• userarg — in the extended use case this argument is passed unchanged to each of the memory management functions each time they are called.
• malloc — the function that will be used for creating response dicts (and the members within the response dicts). by default the system malloc is used.
• realloc — the function that will be used for creating response dicts (and the members within the response dicts). by default the system realloc is used.
• free — the function that will be used for releasing storage for response dicts (and the members within the response dicts). by default the system free is used.

---

🌈 DESCRIPTION (LONG) 🌈

lots of calls in the DNS API require a DNS context. a DNS context holds the info the API needs in order to process DNS calls — like the locations of upstream DNS servers, DNSSEC trust anchors, and so on. the internal structure of the DNS context is opaque, and might be different on each OS. when a context is passed to any function, it must be an allocated context; the context must not be NULL. 🚫

a typical app using this API doesn't need to know anything about contexts. basically: app creates a default context, uses it in the functions that require a context, then deallocates it when done. context manipulation is available for the more DNS-aware programs, but it's unlikely to be interesting to apps that just want the results of lookups for A, AAAA, SRV, and PTR records.

it's expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile. a context should not be used by multiple threads: create a new context for use on a different thread. it is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread. many contexts, one thread? iconic. 👑

when the context is used in the API for the first time and set_from_os is 1, the API starts replacing some of the values with values from the OS — like the ones you'd find in res_query(3), /etc/resolv.conf, and so on — then proceeds with the new function. some advanced users will not want the API to change the values to the OS's defaults; if set_from_os is 0, the API will not do any updates to the initial values based on changes in the OS. for example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP. 🎯

---

⭐ RETURN VALUES ⭐

upon successful completion, each of these functions return GETDNS_RETURN_GOOD. otherwise, these error values come back at you:

• GETDNS_RETURN_GENERIC_ERROR — memory allocation failed or some other untoward thing happened while initializing the context 😭
• GETDNS_RETURN_BAD_CONTEXT — if the context pointer is invalid (getdns_context_destroy)

the getdns_dict returned by getdns_context_get_api_information must be destroyed by the caller, and it includes these name/value pairs:

• version_string — a bindata containing a printable string of the version of the DNS API implemented by this library
• implementation_string — a bindata containing a printable string set by the implementation
• resolution_type — an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB
• all_context — a getdns_dict with names for all the types of context, feed it to getdns_pretty_print_dict (3) for something easily readable ✨

---

🎀 EXAMPLES 🎀

TBD

(yes bestie, it literally just says TBD. the examples are still loading. we wait. 🙈)

---

🍓 FILES 🍓

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

---

💜 SEE ALSO 💜

libgetdns(3), getdns_address(3), getdns_address_sync(3), getdns_context_set(3), getdns_context_set_context_update_callback(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 🫶 this was getdns 1.7.3, dated December 2015 — thank you for coming to my ted talk, go create a context, stay hydrated, and remember: destroy what you create. mwah 💋✨