ARES_REINIT(3)

💖 ARES_REINIT(3) 💖

ok so bestie, we're deep in the Library Functions Manual section today and this one is a certified glow-up function. it's called ares_reinit and it's literally here to give your resolver channel a little refresh from the system config. no biggie. 🦋

✨ NAME ✨

ares_reinit — reinitialize a resolver channel from system configuration. that's it, that's the vibe. 💅

🌸 SYNOPSIS 🌸

#include <ares.h>

int ares_reinit(ares_channel_t *channel)

👑 DESCRIPTION 👑

ok so the way that ares_reinit(3) works is: it re-reads the system configuration and then safely applies that config to the channel you already have. no destroying, no rebuilding from scratch, just a lil makeover on the existing one. ✨

and here's the part that matters, lowkey the most important thing: system configuration will never override user-provided settings. like, if you set stuff yourself via ares_init_options(3) or ares_set_servers(3), that's yours, bestie, and the system config is not about to come in and touch it. boundaries. 🫶

Any existing queries will be automatically requeued if the server they are currently assigned to is removed from the system configuration. so like, no queries get ghosted, they just get reassigned to a new server. iconic behaviour honestly. 🔥

Also heads up: this function may cause additional file descriptors to be created, and existing ones to be destroyed if server configuration has changed. so yeah, fds are moving around. keep up. 💀

0d safety, will spawn a background thread to read the configuration and apply it. 🧚

It is crucial that developers use the ARES_OPT_SOCK_STATE_CB or ARES_OPT_EVENT_THREAD so that notifications of changes are alerted. If using ares_getsock(3) or ares_fds(3), no notification is possible which could cause a stall. 🚨

like genuinely, do not skip that part. if you're on ares_getsock(3) or ares_fds(3) and you're expecting a notification, it is not coming, and you will stall. not cute. 😭

⭐ RETURN VALUES ⭐

ares_reinit(3) can return any of the following values, and every one of them is here so nobody gets surprised:

• ARES_SUCCESS — Initialization succeeded. slay, you're done. 🎀
• ARES_EFILE — A configuration file could not be read. oop, the file said no. 🙈
• ARES_ENOMEM — The process's available memory was exhausted. out of memory, out of vibes. 💀

🌈 AVAILABILITY 🌈

This function was first introduced in c-ares version 1.22.0. so if you're on anything older, bestie, it's simply not there. ✨

💜 SEE ALSO 💜

• ares_init(3)
• ares_init_options(3)
• ares_destroy(3)
• ares_dup(3)
• ares_library_init(3)
• ares_set_servers(3)
• ares_threadsafety(3)

go read those too, iykyk. 📚

and that's the whole page, bestie! 🦋 this one dropped on 12 November 2023 and lives in the Library Functions Manual (c-ares, obviously, the version that brought us 1.22.0). go forth and reinit responsibly. mwah. 💖🎀✨