getdns_general(3)

🌸 NAME 🌸

okay so this is getdns_general(3), straight out of the getdns manual, and it's the page for getdns_general and getdns_general_sync — they do a getdns DNS lookup. that's it, that's the whole job, and they ate 💅

---

📚 LIBRARY 📚

DNS Resolver library (libgetdns, -lgetdns). yes bestie, you gotta link it.

---

✨ SYNOPSIS ✨

#include <getdns.h>

getdns_return_t
getdns_general (getdns_context *context,
   const char *name,
   uint16_t request_type
   getdns_dict *extensions,
   void *userarg,
   getdns_transaction_t *transaction_id,
   getdns_callback_t callbackfn)

getdns_return_t
getdns_general_sync (getdns_context *context,
   const char *name,
   uint16_t request_type
   getdns_dict *extensions,
   getdns_dict **response)

---

💖 DESCRIPTION 💖

So getdns_general(3) and getdns_general_sync are the public entry points into the getdns API library — they go get you any valid responses to a query from the DNS. and real talk: other namespaces in the context are not used here, so don't come looking for them 🫶

ngl, most typical use cases for applications are probably already satisfied by just calling getdns_address(3) instead, which would replace getaddrinfo(3). so like… check that first if it's giving what you need 🌈

• context — a pointer to the previously created DNS context you're using for this DNS request. see getdns_context (3).
• name — the ASCII-based domain name being looked up, as a string. it can <em>also</em> be an IPv4 or IPv6 address for request types that take addresses instead of domain names, like PTR. the values here follow the rules in section 2.1 of RFC 4343, which is what lets non-ASCII octets and special characters exist in labels. iconic of them tbh.
• request_type — specifies the RRtype for the query; the RRtype numbers live in the IANA registry. for example, to get the NS records, request_type would be 2. the API also has defined macros for most of the RRtypes by name, and every one of those definition names starts with "GETDNS_RRTYPE_". so for example, to get the NS records, you can also set request_type to GETDNS_RRTYPE_NS. two roads, same slay ✨
• extensions — extensions for this request, NULL if no extensions. see libgetnds (3) for a detailed description of extensions.
• userarg — returned to the callback function untouched, can be NULL. it's just vibing, it does not get processed, no cap.
• transaction_id — populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, and it's set to 0 if the function fails.
• callbackfn — non-NULL pointer to a callback function defined by the application, typically used to process the response. only the asynchronous signature accepts a callback function — the synchronous signature does not include a callback. see libgetdns (3) for a more detailed discussion of callback functions.
• response — a getdns_dict type is returned in response and it always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int).

⚠️ the storage associated with response must be freed by a call to getdns_free_sync_request_memory (3). do not forget this one bestie, it's giving memory leak and nobody wants that 😭

---

🔥 RETURN VALUES 🔥

Upon successful completion the functions return GETDNS_RETURN_GOOD. otherwise, these error values come back at you:

• GETDNS_RETURN_BAD_CONTEXT — if the context pointer is invalid, or the context has internal deficiencies.
• GETDNS_RETURN_BAD_DOMAIN_NAME — if the domain name passed to the function is invalid.
• GETDNS_RETURN_EXTENSION_MISFORMAT — if the data type specified in one or more of the extensions does not match the specifications.
• GETDNS_RETURN_GENERIC_ERROR — if some problem was encountered in the function that isn't addressed by one of the more specific return codes. the vague one 💀
• GETDNS_RETURN_INVALID PARAMETER — if one or more parameters has an invalid value.
• GETDNS_RETURN_MEMORY_ERROR — if unable to allocate the memory required.
• GETDNS_RETURN_NO_SUCH_EXTENSION — if one or more of the strings specified in the extensions are not valid.

and the values of status that get included in the response parameter are:

• GETDNS_RESPSTATUS_GOOD — if at least one response was returned.
• GETDNS_RESPSTATUS_NO_NAME — if queries for the name yielded all negative responses.
• GETDNS_RESPSTATUS_ALL_TIMEOUT — if all queries for the name timed out. clocked out, every single one 🙈
• GETDNS_RESPSTATUS_NO_SECURE_ANSWERS — if only secure replies are accepted (per context) and at least one response was received, but no DNS responses were secure through DNSSEC.

for a more detailed explanation of the response object, see libgetdns (3).

---

🦋 REQUEST TYPES 🦋

this is the list of the most common request types. a full list of request types in more detail lives at http://www.iana.org/assignments/dns-parameters/dns-parameters.xml — go read it if you want the whole extended universe.

• A — Host address
• AAAA — IPv6 address
• CAA — Certificate Authority Authorization
• CNAME — Canonical name for an alias
• DLV — DNSSEC lookaside validation
• DNAME — DNAME
• DS — Delegation signer
• HINFO — Host information
• KEY — Security key
• MINFO — Mailbox or mail list information
• MX — Mail exchange
• NS — Authoritative name server
• NSEC — Next secure record
• NSEC3 — Next secure record (hashed)
• NSEC3PARAM — NSEC3PARAM
• PTR — Domain name pointer
• RRSIG — Signature for a record set
• SIG — Security signature
• SOA — Marks the start of a zone of authority
• SRV — Server selection
• TA — DNSSEC trust authorities
• TKEY — Transaction key
• TLSA — TLSA
• TSIG — Transaction signature
• TXT — Text strings

---

🎀 EXAMPLES 🎀

TBD

yes literally. that's what it says. not me waiting for the examples to drop 😭

---

📁 FILES 📁

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

---

👑 SEE ALSO 👑

libgetdns(3), getdns_address(3), getdns_context(3), getdns_free_sync_request_memory(3), getdns_hostname(3), getdns_service(3),

---

and that's the whole page bestie, you're so ready. this was getdns 1.7.3, dated December 2015 — old money, still slaying 💜 periodt.