
GETADDRINFO(3)         FreeBSD Library Functions Manual         GETADDRINFO(3)

NNAAMMEE
     ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation
     in protocol-independent manner

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ssoocckkeett..hh>>
     ##iinncclluuddee <<nneettddbb..hh>>

     _i_n_t
     ggeettaaddddrriinnffoo(_c_o_n_s_t _c_h_a_r _*_n_o_d_e_n_a_m_e, _c_o_n_s_t _c_h_a_r _*_s_e_r_v_n_a_m_e,
             _c_o_n_s_t _s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_h_i_n_t_s, _s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_*_r_e_s)

     _v_o_i_d
     ffrreeeeaaddddrriinnffoo(_s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_a_i)

     _c_h_a_r _*
     ggaaii__ssttrreerrrroorr(_i_n_t _e_c_o_d_e)

DDEESSCCRRIIPPTTIIOONN
     The ggeettaaddddrriinnffoo() function is defined for protocol-independent nodename-
     to-address translation.  It performs functionality of gethostbyname(3)
     and getservbyname(3),  in more sophisticated manner.

     The addrinfo structure is defined as a result of including the <netdb.h>
     header:

     struct addrinfo {                                                  *
          int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
          int     ai_family;    /* PF_xxx */
          int     ai_socktype;  /* SOCK_xxx */
          int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
          size_t  ai_addrlen;   /* length of ai_addr */
          char   *ai_canonname; /* canonical name for nodename */
          struct sockaddr  *ai_addr; /* binary address */
          struct addrinfo  *ai_next; /* next structure in linked list */
     };

     The _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e arguments are pointers to null-terminated
     strings or NULL. One or both of these two arguments must be a non-NULL
     pointer.  In the normal client scenario, both the _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e
     are specified.  In the normal server scenario, only the _s_e_r_v_n_a_m_e is spec-
     ified.  A non-NULL _n_o_d_e_n_a_m_e string can be either a node name or a numeric
     host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
     address). A non-NULL _s_e_r_v_n_a_m_e string can be either a service name or a
     decimal port number.

     The caller can optionally pass an addrinfo structure, pointed to by the
     third argument, to provide hints concerning the type of socket that the
     caller supports.  In this _h_i_n_t_s structure all members other than
     _a_i___f_l_a_g_s, _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l must be zero or a NULL
     pointer.  A value of PF_UNSPEC for _a_i___f_a_m_i_l_y means the caller will accept
     any protocol family.  A value of 0 for _a_i___s_o_c_k_t_y_p_e means the caller will
     accept any socket type.  A value of 0 for _a_i___p_r_o_t_o_c_o_l means the caller
     will accept any protocol.  For example, if the caller handles only TCP
     and not UDP, then the _a_i___s_o_c_k_t_y_p_e member of the hints structure should be
     set to SOCK_STREAM when ggeettaaddddrriinnffoo() is called.  If the caller handles
     only IPv4 and not IPv6, then the _a_i___f_a_m_i_l_y member of the _h_i_n_t_s structure
     should be set to PF_INET when ggeettaaddddrriinnffoo() is called.  If the third ar-
     gument to ggeettaaddddrriinnffoo() is a NULL pointer, this is the same as if the
     caller had filled in an addrinfo structure initialized to zero with
     _a_i___f_a_m_i_l_y set to PF_UNSPEC.


     Upon successful return a pointer to a linked list of one or more addrinfo
     structures is returned through the final argument.  The caller can pro-
     cess each addrinfo structure in this list by following the _a_i___n_e_x_t point-
     er, until a NULL pointer is encountered.  In each returned addrinfo
     structure the three members _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l are
     the corresponding arguments for a call to the ssoocckkeett() function.  In each
     addrinfo structure the _a_i___a_d_d_r member points to a filled-in socket ad-
     dress structure whose length is specified by the _a_i___a_d_d_r_l_e_n member.

     If the AI_PASSIVE bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s struc-
     ture, then the caller plans to use the returned socket address structure
     in a call to bbiinndd().  In this case, if the _n_o_d_e_n_a_m_e argument is a NULL
     pointer, then the IP address portion of the socket address structure will
     be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
     address.

     If the AI_PASSIVE bit is not set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s
     structure, then the returned socket address structure will be ready for a
     call to ccoonnnneecctt() (for a connection-oriented protocol) or either
     ccoonnnneecctt(), sseennddttoo(),or sseennddmmssgg() (for a connectionless protocol). In this
     case, if the _n_o_d_e_n_a_m_e argument is a NULL pointer, then the IP address
     portion of the socket address structure will be set to the loopback ad-
     dress.

     If the AI_CANONNAME bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s struc-
     ture, then upon successful return the _a_i___c_a_n_o_n_n_a_m_e member of the first
     addrinfo structure in the linked list will point to a null-terminated
     string containing the canonical name of the specified _n_o_d_e_n_a_m_e.

     If the AI_NUMERICHOST bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s
     structure, then a non-NULL _n_o_d_e_n_a_m_e string must be a numeric host address
     string.  Otherwise an error of EAI_NONAME is returned.  This flag pre-
     vents any type of name resolution service (e.g., the DNS) from being
     called.

     All of the information returned by ggeettaaddddrriinnffoo() is dynamically allocat-
     ed: the addrinfo structures, and the socket address structures and canon-
     ical node name strings pointed to by the addrinfo structures.  To return
     this information to the system the function Fn freeaddrinfo is called.
     The _a_d_d_r_i_n_f_o structure pointed to by the _a_i _a_r_g_u_m_e_n_t is freed, along with
     any dynamic storage pointed to by the structure.  This operation is re-
     peated until a NULL _a_i___n_e_x_t pointer is encountered.

     To aid applications in printing error messages based on the EAI_xxx codes
     returned by ggeettaaddddrriinnffoo(), ggaaii__ssttrreerrrroorr() is defined.  The argument is
     one of the EAI_xxx values defined earlier and the return value points to
     a string describing the error.  If the argument is not one of the EAI_xxx
     values, the function still returns a pointer to a string whose contents
     indicate an unknown error.

FFIILLEESS
     /etc/hosts
     /etc/host.conf
     /etc/resolv.conf

DDIIAAGGNNOOSSTTIICCSS
     Error return status from ggeettaaddddrriinnffoo() is zero on success and non-zero on
     errors.  Non-zero error codes are defined in <netdb.h>, and as follows:

     EAI_ADDRFAMILY  address family for nodename not supported
     EAI_AGAIN       temporary failure in name resolution
     EAI_BADFLAGS    invalid value for ai_flags
     EAI_FAIL        non-recoverable failure in name resolution


     EAI_FAMILY      ai_family not supported
     EAI_MEMORY      memory allocation failure
     EAI_NODATA      no address associated with nodename
     EAI_NONAME      nodename nor servname provided, or not known
     EAI_SERVICE     servname not supported for ai_socktype
     EAI_SOCKTYPE    ai_socktype not supported
     EAI_SYSTEM      system error returned in errno

     If called with proper argument, ggaaii__ssttrreerrrroorr() returns a pointer to a
     string describing the given error code.  If the argument is not one of
     the EAI_xxx values, the function still returns a pointer to a string
     whose contents indicate an unknown error.

SSEEEE AALLSSOO
     getnameinfo(3),  gethostbyname(3),  getservbyname(3),  hosts(5),
     services(5),  hostname(7),  named(8)

     R. Gilligan, S.  Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter-
     face Extensions for IPv6,'' RFC2133, April 1997.

HHIISSTTOORRYY
     The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
     kit.

SSTTAANNDDAARRDDSS
     The ggeettaaddddrriinnffoo() function is defined IEEE POSIX 1003.1g draft specifica-
     tion, and documented in ``Basic Socket Interface Extensions for IPv6''
     (RFC2133).

BBUUGGSS
     The text was shamelessly copied from RFC2133.

KAME                             May 25, 1995                                3
