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(const 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.