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)