ARES_SET_SERVERS(3)

💅 ARES_SET_SERVERS(3) — Library Functions Manual

okay bestie, welcome to the ares_set_servers page 💖 this is from the Library Functions Manual, and it's all about telling your ares channel which name servers to talk to. spoiler alert: it's deprecated, so enjoy the nostalgia era while it lasts 🎀

---

✨ NAME ✨

ares_set_servers, ares_set_servers_ports — initialize name server configuration for an ares channel. (deprecated 👑)

---

🌸 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 the way that ares_set_servers(3) works is: it initializes the name servers configuration for the channel data identified by channel, and it pulls all that from a servers pointer. That pointer is a linked list of ares_addr_node structs, and those structs are holding your name servers address data. literally the whole squad 🫶

That name server linked list pointer? It can 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. we don't gatekeep how you built it 💜

Now ares_set_servers_ports(3) is the glow-up version: it also lets you specify the UDP and TCP ports to be used for communication on a per-server basis. iconique. The linked list argument you hand it 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.

⚠️ okay important, 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 desired ones must be specified in a single list. no piecemeal, no drip-feeding, one list, periodt.

Though not recommended, passing NULL will clear all configured servers and make an inoperable channel 😭 it may be advantageous for test simulation but unlikely to be useful in production. so like… slay for testing, never for prod, fr fr.

Also! The function does not take ownership of the linked list argument. The caller is responsible for freeing the linked list when no longer needed. don't forget or that's a leak 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. yes it ate that up ✨

As of v1.22.0 this function can be called on an active channel with running queries. previously it would return ARES_ENOTIMP. glow up confirmed 🔥

---

🌈 RETURN VALUES 🌈

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

• ARES_SUCCESS — the name servers configuration was successfully initialized. we love to see it 💖
• ARES_ENOMEM — the process's available memory was exhausted. rip, out of memory 😭
• ARES_ENODATA — the channel data identified by channel was invalid. that channel said no ❌
• ARES_ENOTINITIALIZED — c-ares library initialization not yet performed. you gotta init first, bestie 🙈

---

💫 SEE ALSO 💫

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

go read those 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 it's giving "old faithful but the new one is better" 💅

---

⭐ 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. a whole era of lore 🌸

---

okay that's the whole page bestie, you're officially fluent 💖 this manual page was served up on 5 March 2010 as part of ARES_SET_SERVERS(3), and that's the vibe check, periodt 👑✨