getdns_hostname(3)

💖 getdns_hostname — bestie edition 💖

okay so before we even get into it: this is a page from the getdns manual, section 3, and it's all about getdns_hostname. reverse lookups. the whole "i have an address, who lives there" situation. it's giving detective energy fr fr 🔍✨

---

🌸 NAME 🌸

getdns_hostname, getdns_hostname_sync — get hostname by address

---

🎀 LIBRARY 🎀

DNS Resolver library (libgetdns, -lgetdns)

---

✨ SYNOPSIS ✨

#include <getdns.h>

getdns_return_t
getdns_hostname (getdns_context *context,
   getdns_dict *address,
   getdns_dict *extensions,
   void *userarg,
   getdns_transaction_t *transaction_id,
   getdns_callback_t callbackfn)

getdns_return_t
getdns_hostname_sync (getdns_context *context,
   getdns_dict *address,
   getdns_dict *extensions,
   getdns_dict **response)

---

🦋 DESCRIPTION 🦋

so getdns_hostname(3) and getdns_hostname_sync are the public entry points into the getdns API library, and what they do is retrieve the host name given an address. that's it, that's the job. you hand it an address, it goes and finds out what name is attached to it. queen behavior. 👑

here's the whole cast of characters:

• context — a pointer to the previously created DNS context that's gonna be used with this DNS request. see getdns_context (3) if you need the lore.
• address — a getdns_dict structure containing two names: address_type (whose value is bindata and is either "IPv4" or "IPv6") and address_data whose value is bindata. yes bestie, both of those. you can't skip one. 🙈
• extensions — extensions for this request, NULL if there are no extensions. see libgetdns (3) for a detailed description of extensions.
• userarg — returned to the callback function untouched, can be NULL. it's like a little gift you hand over and get back exactly the way you gave it. no notes. 🎁
• transaction_id — populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails.
• callbackfn — a 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 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 this must be freed by a call to getdns_free_sync_request_memory (3).

not me reminding you again: free that memory. getdns_free_sync_request_memory (3). do not leave it hanging, that's not the vibe. 💅

---

💜 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 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 not addressed by one of the more specific return codes
• 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

🍓 the values of status in the response parameter 🍓

• 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
• GETDNS_RESPSTATUS_NO_SECURE_ANSWERS — if only secure replies 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)

---

🌈 EXAMPLES 🌈

TBD

ik ik, TBD. the examples are still in the group chat typing… bestie is working on it 🫶

---

🧚 FILES 🧚

/etc/hosts
/etc/resolv.conf

---

👑 SEE ALSO 👑

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

---

okay that's the whole page, go forth and resolve some names 💖✨

this was getdns 1.7.3, dated December 2015 — periodt, that's a wrap 🎀🦋💅