getdns_service(3)

💖 getdns_service(3) 💖

okay bestie, welcome to the getdns manual, part of the getdns docs situation. this one's about looking up a service, and yes it's as cute as it sounds 🌸

---

✨ NAME ✨

getdns_service, getdns_service_sync — getdns lookup of a service 🦋

---

📚 LIBRARY 📚

DNS Resolver library (libgetdns, -lgetdns)

---

🌟 SYNOPSIS 🌟

#include <getdns.h>

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

getdns_return_t
getdns_service_sync (getdns_context *context,
   const char *name,
   getdns_dict *extensions,
   getdns_dict **response)

---

🫶 DESCRIPTION 🫶

so. getdns_service (3) and getdns_service_sync are the public entry points into the getdns API library, and their whole job is retrieving the SRV information given a name. iconic behavior honestly ✨

• context — a pointer to the previously created DNS context that's gonna be used with this DNS request. go peek at getdns_context (3) if you need the lore 💅
• name — the service name to resolve 🎀
• extensions — extensions for this request, NULL if there are no extensions. libgetdns (3) has a whole detailed description of extensions, go read it bestie
• userarg — this gets returned to the callback function untouched, and it can be NULL 🌸
• transaction_id — populated by the API, and used to identify the callback (for example, to hand to getdns_cancel_callback). it can be NULL, and it's 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, no cap. libgetdns (3) has a more detailed discussion of callback functions if you wanna get deep 🧚
• 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 this must be freed by a call to getdns_free_sync_request_memory (3) — don't forget, or that's a memory leak and we don't do that here 🙈

---

👑 RETURN VALUES 👑

upon successful completion the functions return GETDNS_RETURN_GOOD 💖 otherwise, here's the error values that can 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
• 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 status values 🌈

the values of status 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 😭
• 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) 📖

---

💅 EXAMPLES 💅

TBD 🫠 (the docs said TBD and honestly, same)

---

🍓 FILES 🍓

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

---

🔥 SEE ALSO 🔥

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

---

bestie reminder: response memory goes to getdns_free_sync_request_memory (3) or it just lives in your heap forever. free your girl. 🫶

---

and that's the whole page! this one's from getdns 1.7.3, dated December 2015 — yeah she's vintage, and she still ate 💖✨👑