NAME

       ares_set_servers_csv, ares_set_servers_ports_csv, ares_get_servers_csv - Set or Get a list of DNS servers
       used for queries.

SYNOPSIS

       #include <ares.h>

       int ares_set_servers_csv(ares_channel_t *channel, const char* servers)

       int ares_set_servers_ports_csv(ares_channel_t *channel, const char* servers)

       char *ares_get_servers_csv(ares_channel_t *channel)

DESCRIPTION

       The ares_set_servers_csv and ares_set_servers_ports_csv functions set the list of DNS servers that c-ares
       will  query.   As  of  v1.22.0  this  function  can  be called on an active channel with running queries,
       previously it would return ARES_ENOTIMP.

       Though not recommended, passing NULL for servers will clear all configured servers and make an inoperable
       channel, this may be advantageous for test simulation but unlikely to be useful in production.

       The ares_get_servers_csv retrieves the list of servers in comma delimited format.

       The input and output format is a comma separated list of servers.  Each server entry  may  contain  these
       forms:

       ip[:port][%iface]

       The  ip  may  be  encapsulated  in square brackets ([ ]), and must be if using ipv6 and also specifying a
       port.

       The port is optional, and will default to 53 or the value specified in ares_init_options(3).

       The iface is specific to IPv6 link-local servers (fe80::/10) and should not otherwise be used.

       For example:

       192.168.1.100,192.168.1.101:53,[1:2:3::4]:53,[fe80::1]:53%eth0

       As of c-ares 1.24.0, ares_set_servers_csv and ares_set_servers_ports_csv are identical.   Prior  versions
       would  simply omit ports in ares_set_servers_csv but due to the addition of link local interface support,
       this difference was removed.

RETURN VALUES

       ares_set_servers_csv(3) and ares_set_servers_ports_csv(3) may return any of the following values:

       ARES_SUCCESS   The name servers configuration was successfully initialized.

       ARES_ENOMEM    The process's available memory was exhausted.

       ARES_ENODATA   The channel data identified by channel was invalid.

       ARES_ENOTINITIALIZED
                      c-ares library initialization not yet performed.

       ares_get_servers_csv(3) returns a string representing the servers configured which  must  be  freed  with
       ares_free_string(3).  If it returns NULL, this is an out of memory condition.

SEE ALSO

       ares_set_servers(3)

AVAILABILITY

       ares_set_servers_csv  was  added  in  c-ares 1.7.2 ares_set_servers_ports_csv was added in c-ares 1.11.0.
       ares_get_servers_csv was added in c-ares 1.24.0.

AUTHOR

       Ben Greear

                                                   5 Dec 2023                            ARES_SET_SERVERS_CSV(3)