ARES_GET_SERVERS(3)

💖 ARES_GET_SERVERS 💖

okay bestie, welcome to the ares_get_servers(3) page — and yeah, it's the one with the sister function ares_get_servers_ports. Together they retrieve name servers from an initialized ares_channel. And listen… they're deprecated 🥲 (more on that below, don't skip it).

✨ 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 ares_get_servers(3) grabs the name servers config out of the channel data you point at with channel, and hands it back to you as a linked list of ares_addr_node structs — with a pointer to the first node sitting at the address you passed as servers. cute, right? 🎀

ares_get_servers_ports(3) does the same thing but it ALSO scoops up any per-server port info that may have been configured before, returning you a linked list of ares_addr_port structures. extra detail, love that for us 💅

As the caller you've got options: you can walk the returned name server linked list node by node, or you can just yeet it straight in as input for ares_set_servers(3) / ares_set_servers_ports(3). But do NOT shrink or extend the list yourself — that's not your business, bestie 🙈

Every single node of that name server linked list lives in memory that's dynamically allocated and managed by c-ares. So it's your responsibility to free the whole resulting linked list with ares_free_data(3) once you don't need it anymore. not me forgetting to free and leaking… couldn't be me 💀

Also iconic: this function handles IPv4 and IPv6 name server addresses at the same time, which makes ares_save_options(3) with optmask ARES_OPT_SERVERS functionally obsolete — except for IPv4-only name server usage. the range, honestly 👑

⭐ RETURN VALUES ⭐

This function may return any of the following values:

• 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 the reason is lowkey important: they lack the ability to store the entire server configuration. 😬 Use ares_get_servers_csv(3) instead. periodt.

💜 and that's the whole page, bestie! this one's from the Library Functions Manual, page ARES_GET_SERVERS(3), dated 5 March 2010 — yes she's been around a minute, and yes she's deprecated, we still love her 🫶 bye!! 🌸✨