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

FreeBSD Manual Pages


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

       ares_getaddrinfo	- Initiate a host query	by name	and service

       #include	<ares.h>

       typedef void (*ares_addrinfo_callback)(void *arg, int status,
	    int	timeouts, struct ares_addrinfo *result)

       void ares_getaddrinfo(ares_channel channel, const char *name,
	    const char*	service, const struct ares_addrinfo_hints *hints,
	    ares_addrinfo_callback callback, void *arg)

       The  ares_getaddrinfo  function	initiates  a host query	by name	on the
       name service channel identified by channel.  The	name and  service  pa-
       rameters	 give  the  hostname and service as NULL-terminated C strings.
       The hints parameter is an ares_addrinfo_hints structure:

	      struct ares_addrinfo_hints {
		int ai_flags;
		int ai_family;
		int ai_socktype;
		int ai_protocol;

	      Specifies	desired	address	family.	AF_UNSPEC  means  return  both
	      AF_INET and AF_INET6.

	      Specifies	 desired  socket  type,	 for  example  SOCK_STREAM  or
	      SOCK_DGRAM.  Setting this	to 0 means any type.

	      Setting this to 0	means any protocol.

	      Specifies	additional options, see	below.

			  If this option is set	service	field will be  treated
			  as a numeric value.

       ARES_AI_CANONNAME  The  ares_addrinfo structure will return a canonical
			  names	list.

       ARES_AI_NOSORT	  Result addresses will	not be sorted and  no  connec-
			  tions	to resolved addresses will be attempted.

       ARES_AI_ENVHOSTS	  Read	hosts  file path from the environment variable

       When the	query is complete or has failed, the ares library will	invoke
       callback.   Completion  or failure of the query may happen immediately,
       or may happen during a later call to  ares_process(3),  ares_destroy(3)
       or ares_cancel(3).

       The  callback argument arg is copied from the ares_getaddrinfo argument
       arg.  The callback argument status indicates  whether  the  query  suc-
       ceeded  and,  if	 not, how it failed.  It may have any of the following

       ARES_SUCCESS	  The host lookup completed successfully.

       ARES_ENOTIMP	  The ares library does	not know how to	find addresses
			  of type family.

       ARES_ENOTFOUND	  The name was not found.

       ARES_ENOMEM	  Memory was exhausted.

       ARES_ECANCELLED	  The query was	cancelled.

       ARES_EDESTRUCTION  The name service channel channel is being destroyed;
			  the query will not be	completed.

       On successful completion	of the query,  the  callback  argument	result
       points  to  a struct ares_addrinfo which	contains two linked lists, one
       with resolved addresses and another with	canonical names.

	      struct ares_addrinfo {
		struct ares_addrinfo_cname *cnames;
		struct ares_addrinfo_node  *nodes;

       ares_addrinfo_node structure is similar to RFC3493 addrinfo, but	 with-
       out canonname and with extra ttl	field.

	      struct ares_addrinfo_node	{
		int			   ai_ttl;
		int			   ai_flags;
		int			   ai_family;
		int			   ai_socktype;
		int			   ai_protocol;
		ares_socklen_t		   ai_addrlen;
		struct sockaddr		  *ai_addr;
		struct ares_addrinfo_node *ai_next;

       ares_addrinfo_cname  structure  is a linked list	of CNAME records where
       ttl is a	time to	live alias is a	label of the resource record and  name
       is  a  value  (canonical	 name)	of  the	 resource record.  See RFC2181
       10.1.1. CNAME terminology.

	      struct ares_addrinfo_cname {
		int			    ttl;
		char			   *alias;
		char			   *name;
		struct ares_addrinfo_cname *next;

       The reserved memory has to be deleted by	ares_freeaddrinfo.

       The result is sorted according to RFC6724 except:
	- Rule 3 (Avoid	deprecated addresses)
	- Rule 4 (Prefer home addresses)
	- Rule 7 (Prefer native	transport)

       Please note that	the function will attempt a connection on each of  the
       resolved	addresses as per RFC6724.


       Christian Ammer
       Andrew Selivanov	<>

				4 November 2018		   ARES_GETADDRINFO(3)


Want to link to this manual page? Use this URL:

home | help