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,  pre-
       viously it would	return ARES_ENOTIMP.

       Though not recommended, passing NULL for	servers	will clear all config-
       ured  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	delim-
       ited format.

       The  input and output format is a comma separated list of servers.  Two
       formats 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
	   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.

       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 techni-
	   cally 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
       defined in the future.

	   tcpport  - TCP port to use, only for	dns:// scheme. The port	speci-
	   fied	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
	   component of	the URI	contains a hostname, this is used  to  specify
	   the	ip address of the hostname. If not specified, will need	to use
	   a non-secure	server to perform a DNS	lookup to retrieve this	infor-
	   mation. It is always	recommended to have both the  ip  address  and
	   fully qualified domain name specified.

	   hostname  -	Only for dns+tls:// and	dns+https://. If the authority
	   component of	the URI	contains an ip address,	this is	used to	 spec-
	   ify	the  fully  qualified domain name of the server. If not	speci-
	   fied, 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 implementa-
       tions 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 lo-
       cal interface support, 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 initial-
		      ized.

       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 con-
       figured 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_set_servers_ports_csv&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help