ARES_SET_SERVERS(3)

💖 ARES_SET_SERVERS 💖

okay bestie, we're doing ares_set_servers(3) and ares_set_servers_ports(3) today, and the tea is: these two are deprecated 🙈 but you still gotta know them, so let's go. This is a Library Functions Manual situation, and we're talking about initializing name server configuration for an ares channel. (yes, that's the deprecation in the NAME line too, she's not hiding it)

✨ SYNOPSIS ✨

#include <ares.h>

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

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

🦋 DESCRIPTION 🦋

So like, ares_set_servers(3) initializes the name servers configuration for the channel data that channel points to. Where does it get them from? From servers, which is a pointer to a linked list of ares_addr_node structs holding name server address data. it's giving "here's my whole squad, in order" 💅

That linked list pointer you pass in? It can totally be the result of a previous call to ares_get_servers(3), or honestly just a linked list of ares_addr_node structs you set up by other means. no judgement, bestie 🫶

Now ares_set_servers_ports(3) is the extra one — she also lets you specify the UDP and TCP ports to be used for communication, and she does it on a per-server basis. iconic tbh. And same deal: the linked list argument may be the result of a previous call to ares_get_servers_ports(3), or a linked list of ares_addr_port_node structs set up by other means. ✨

heads up, this part matters: this function replaces any potentially previously configured name servers with the ones given in the linked list. so if you want more than one name server on a channel, ALL the ones you want have to be in a single list. one list, everybody in it, periodt.

And, though it's not recommended, passing NULL will clear all configured servers and make an inoperable channel. 😭 It may be advantageous for test simulation, but it's unlikely to be useful in production. so like... test vibes only, don't ship that.

Also important: the function does not take ownership of the linked list argument. The caller is responsible for freeing the linked list when it's no longer needed. that's on you, bestie 🎀

This function is capable of handling IPv4 and IPv6 name server addresses simultaneously, which renders ares_init_options(3) with optmask ARES_OPT_SERVERS functionally obsolete — except for IPv4-only name server usage. we love a glow-up 🌈

And as of v1.22.0, this function can be called on an active channel with running queries. Previously it would return ARES_ENOTIMP. character development fr fr 💀✨

🌸 RETURN VALUES 🌸

ares_set_servers(3) may return any of the following values:

• ARES_SUCCESS — the name servers configuration was successfully initialized. slay 💖
• ARES_ENOMEM — the process's available memory was exhausted. rip 😭
• ARES_ENODATA — the channel data identified by channel was invalid. not the vibe check failing 💀
• ARES_ENOTINITIALIZED — c-ares library initialization not yet performed. you gotta warm her up first bestie 🧚

🎀 SEE ALSO 🎀

• ares_set_servers_csv(3)
• ares_get_servers(3)
• ares_init_options(3)
• ares_dup(3)

go read these too, iykyk 👑

💅 NOTES 💅

Deprecated functions as of c-ares 1.24.0 due to inability to set all available server options. Use ares_set_servers_csv(3). like genuinely, bestie, use the CSV one. this is your sign 🫶

⭐ AVAILABILITY ⭐

ares_set_servers(3) was added in c-ares 1.7.1; ares_set_servers_ports(3) was added in c-ares 1.11.0. throwback era honestly 🌸

and that's the whole page, bestie — this one lives in the Library Functions Manual and it's dated 5 March 2010 💖 go configure responsibly, mwah 💅✨