ARES_SAVE_OPTIONS(3)

💾 ARES_SAVE_OPTIONS(3) 💾

okay so bestie, welcome to the manual page for ares_save_options — it's a libc-ares function and it's literally here to save configuration values obtained from an initialized ares_channel. cute, right? let's get into it ✨

🌸 SYNOPSIS 🌸

#include <ares.h>

int ares_save_options(const ares_channel_t *channel,
                      struct ares_options *options, int *optmask)

🎀 DESCRIPTION 🎀

so the way ares_save_options(3) works is: it takes the channel data that's identified by channel, and it saves all of that into the options struct (which is identified by options, obviously 💅). then it also saves the mask of options that are set into that integer pointer — the one passed by reference — which is identified by optmask. yes, pointer-to-int, she's fancy.

and here's the slay part: the resultant options and optmask can be passed directly into ares_init_options. like, no extra steps, no re-formatting, it just goes. 🫶

but listen — when you're done with the options and you don't need them anymore, you have to call ares_destroy_options to free any associated memory. do not skip this, bestie, we do not leak in this house. 😭

🦋 RETURN VALUES 🦋

ares_save_options(3) can return any of these little guys:

• ARES_SUCCESS — the channel data was successfully stored 💖
• ARES_ENOMEM — the memory was exhausted 😭
• ARES_ENODATA — the channel data identified by channel were invalid 💀

⚠️ NOTE ⚠️

okay this is the important lore, so pay attention:

since c-ares 1.6.0, the ares_options struct has been "locked" — meaning it will not be extended to cover new functions. periodt. 🔒

this function will keep on functioning, no worries, but it can only return config data that can actually be represented in this config struct — which may no longer be the complete set of config options. so like, it's giving limited. 🙈

meanwhile ares_dup(3) does not have that restriction. just saying. 👑

also!! the ares_options struct can not handle potential IPv6 name servers that the ares channel might be configured to use. so ares_save_options(3) will only return IPv4 servers, if any. that's just how she is. 😔

so if you need to retrieve all the name servers an ares channel might be using, you have to use ares_get_servers(3) instead. no cap, that's the move. ✨

👀 SEE ALSO 👀

• ares_destroy_options(3)
• ares_init_options(3)
• ares_get_servers(3)
• ares_dup(3)

🌈 AVAILABILITY 🌈

ares_save_options(3) was added in c-ares 1.4.0 ⭐

and that's the whole vibe, bestie — this page came to you courtesy of 5 March 2010, the Library Functions Manual, filed under ARES_SAVE_OPTIONS(3). go forth and save those options responsibly 💜🧚