Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
ARES_SET_SERVERS_CSV(3)     Library Functions Manual	 ARES_SET_SERVERS_CSV(3)

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.	Two for-
     mats are available, the typical resolv.conf(5) nameserver format,	as  well
     as a URI format.  Both formats can be used at the same time in the provided
     CSV string.

     The nameserver format is:

     ip[:port][%iface]

	 The ip may be encapsulated in square brackets ([ ]), and must be if us-
	 ing 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.

     nameserver format examples:

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

     The URI format is is made up of these defined schemes:
	 dns:// - Normal DNS server (UDP + TCP). We need to be	careful  not  to
	 conflict with query params defined in RFC4501 since we'd technically be
	 extending this URI scheme. Port defaults to 53.

	 dns+tls:// - DNS over TLS. Port defaults to 853.

	 dns+https:// - DNS over HTTPS. Port defaults to 443.

     Query  parameters	are  defined as below.	Additional parameters may be de-
     fined in the future.

	 tcpport - TCP port to use, only for dns:// scheme. The  port  specified
	 as part of the authority component of the URI will be used for both UDP
	 and TCP by default, this option will override the TCP port.

	 ipaddr  - Only for dns+tls:// and dns+https://. If the authority compo-
	 nent of the URI contains a hostname, this is used to specify the ip ad-
	 dress of the hostname. If not specified, will need to use a  non-secure
	 server  to perform a DNS lookup to retrieve this information. It is al-
	 ways recommended to have both the ip address and fully qualified domain
	 name specified.

	 hostname - Only for dns+tls:// and dns+https://. If the authority  com-
	 ponent  of  the URI contains an ip address, this is used to specify the
	 fully qualified domain name of the server. If not specified, will  need
	 to  use a non-secure server to perform a DNS reverse lookup to retrieve
	 this information. It is always recommended to have both the ip  address
	 and fully qualified domain name specified.

	 domain  -  If	specified,  this server is a domain-specific server. Any
	 queries for this domain will be routed to this server. Multiple servers
	 may be tagged with the same domain.

     URI format Examples:

     dns://8.8.8.8
     dns://[2001:4860:4860::8888]
     dns://[fe80::b542:84df:1719:65e3%en0]
     dns://192.168.1.1:55
     dns://192.168.1.1?tcpport=1153
     dns://10.0.1.1?domain=myvpn.com
     dns+tls://8.8.8.8?hostname=dns.google
     dns+tls://one.one.one.one?ipaddr=1.1.1.1

     NOTE: While we are defining the  scheme  for  things  like  domain-specific
     servers,  DNS  over  TLS and DNS over HTTPS, the underlying implementations
     for those features do not yet exist and therefore will result in errors  if
     they are attempted to be used.

     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 sup-
     port, this difference was removed.

EXAMPLE
     192.168.1.100,[fe80::1]:53%eth0,dns://192.168.1.1?tcpport=1153

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  config-
     ured  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.  URI support was added in c-ares 1.34.0.

				   5 Dec 2023		 ARES_SET_SERVERS_CSV(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ares_get_servers_csv&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help