ARES_GET_SERVERS(3)

💖 ARES_GET_SERVERS(3) 💖

okay bestie, so this is a page from the Library Functions Manual and it's all about ares_get_servers and ares_get_servers_ports — two lil functions that go digging in your ares_channel to find out which name servers it's been configured with. 🎀 heads up tho: they're deprecated (more on that in a sec, don't panic).

✨ NAME ✨

ares_get_servers, ares_get_servers_ports — Retrieve name servers from an initialized ares_channel (deprecated) 💅

🌸 SYNOPSIS 🌸

#include <ares.h>

int ares_get_servers(const ares_channel_t *channel,
                     struct ares_addr_node **servers)

int ares_get_servers_ports(const ares_channel_t *channel,
                           struct ares_addr_port_node **servers)

🦋 DESCRIPTION 🦋

so like, ares_get_servers(3) pulls the name servers configuration out of the channel data that channel points at, and hands it to you as a linked list of ares_addr_node structs — with a pointer to the very first node dropped at the address you passed in servers. it's giving "here's ur lil chain of servers, bestie". ✨

ares_get_servers_ports(3) is the same vibe but extra — it also grabs any per-server port information that might have been configured earlier, and returns a linked list of ares_addr_port structures instead. 🔥

the caller may traverse the returned name server linked list, or honestly just use it directly as suitable input for the ares_set_servers(3) / ares_set_servers_ports(3) functions — but shall not shrink or extend the list on its own. do not touch. hands off. 🙈

every single node of that name server linked list lives in memory that's dynamically allocated and managed by c-ares. so it is your responsibility (yes, yours, main character) to free the resulting linked list using ares_free_data(3) once you don't need it anymore. don't leave it hanging, that's so not slay. 🫶

and the glow-up? this function handles IPv4 and IPv6 name server addresses simultaneously, which lowkey renders ares_save_options(3) with optmask ARES_OPT_SERVERS functionally obsolete — except for IPv4-only name server usage. iykyk. 💀

🌈 RETURN VALUES 🌈

this function may return any of the following values, bestie, so read carefully:

• ARES_SUCCESS — the name servers configuration was successfully retrieved 🎉
• ARES_ENOMEM — the memory was exhausted 😭
• ARES_ENODATA — the channel data identified by channel was invalid. 👀

💜 SEE ALSO 💜

• ares_set_servers(3)
• ares_init_options(3)
• ares_save_options(3)

⭐ AVAILABILITY ⭐

• ares_get_servers(3) was added in c-ares 1.7.1
• ares_get_servers_ports(3) was added in c-ares 1.11.0

🎀 NOTES 🎀

as of c-ares 1.24, these functions are deprecated — and it's because of their lack of ability to store the entire server configuration. 💔 use ares_get_servers_csv(3) instead. periodt.

and that's the whole page, babe! 💅 this one's dated 5 March 2010, it lives in the Library Functions Manual (that's the ARES_GET_SERVERS(3) page title, you already knew that tho), and the source/version line is the same ARES_GET_SERVERS(3) footer energy. go forth, free your linked lists, and slay. 🦋💖✨