1GETADDRINFO(3) FreeBSD Library Functions Manual GETADDRINFO(3) 2 3NNAAMMEE 4 ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr -- nodename-to-address translation 5 in protocol-independent manner 6 7SSYYNNOOPPSSIISS 8 ##iinncclluuddee <<ssyyss//ssoocckkeett..hh>> 9 ##iinncclluuddee <<nneettddbb..hh>> 10 11 _i_n_t 12 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, 13 _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); 14 15 _v_o_i_d 16 ffrreeeeaaddddrriinnffoo(_s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_a_i); 17 18 _c_h_a_r _* 19 ggaaii__ssttrreerrrroorr(_i_n_t _e_c_o_d_e); 20 21DDEESSCCRRIIPPTTIIOONN 22 The ggeettaaddddrriinnffoo() function is defined for protocol-independent nodename- 23 to-address translation. It performs functionality of gethostbyname(3) 24 and getservbyname(3), in more sophisticated manner. 25 26 The addrinfo structure is defined as a result of including the <netdb.h> 27 header: 28 29 struct addrinfo { * 30 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 31 int ai_family; /* PF_xxx */ 32 int ai_socktype; /* SOCK_xxx */ 33 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 34 size_t ai_addrlen; /* length of ai_addr */ 35 char *ai_canonname; /* canonical name for nodename */ 36 struct sockaddr *ai_addr; /* binary address */ 37 struct addrinfo *ai_next; /* next structure in linked list */ 38 }; 39 40 The _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e arguments are pointers to null-terminated 41 strings or NULL. One or both of these two arguments must be a non-NULL 42 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 43 are specified. In the normal server scenario, only the _s_e_r_v_n_a_m_e is spec- 44 ified. A non-NULL _n_o_d_e_n_a_m_e string can be either a node name or a numeric 45 host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex 46 address). A non-NULL _s_e_r_v_n_a_m_e string can be either a service name or a 47 decimal port number. 48 49 The caller can optionally pass an addrinfo structure, pointed to by the 50 third argument, to provide hints concerning the type of socket that the 51 caller supports. In this _h_i_n_t_s structure all members other than 52 _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 53 pointer. A value of PF_UNSPEC for _a_i___f_a_m_i_l_y means the caller will accept 54 any protocol family. A value of 0 for _a_i___s_o_c_k_t_y_p_e means the caller will 55 accept any socket type. A value of 0 for _a_i___p_r_o_t_o_c_o_l means the caller 56 will accept any protocol. For example, if the caller handles only TCP 57 and not UDP, then the _a_i___s_o_c_k_t_y_p_e member of the hints structure should be 58 set to SOCK_STREAM when ggeettaaddddrriinnffoo() is called. If the caller handles 59 only IPv4 and not IPv6, then the _a_i___f_a_m_i_l_y member of the _h_i_n_t_s structure 60 should be set to PF_INET when ggeettaaddddrriinnffoo() is called. If the third 61 argument to ggeettaaddddrriinnffoo() is a NULL pointer, this is the same as if the 62 caller had filled in an addrinfo structure initialized to zero with 63 _a_i___f_a_m_i_l_y set to PF_UNSPEC. 64 65 Upon successful return a pointer to a linked list of one or more addrinfo 66 structures is returned through the final argument. The caller can 67 process each addrinfo structure in this list by following the _a_i___n_e_x_t 68 pointer, until a NULL pointer is encountered. In each returned addrinfo 69 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 70 the corresponding arguments for a call to the ssoocckkeett() function. In each 71 addrinfo structure the _a_i___a_d_d_r member points to a filled-in socket 72 address structure whose length is specified by the _a_i___a_d_d_r_l_e_n member. 73 74 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- 75 ture, then the caller plans to use the returned socket address structure 76 in a call to bbiinndd(). In this case, if the _n_o_d_e_n_a_m_e argument is a NULL 77 pointer, then the IP address portion of the socket address structure will 78 be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 79 address. 80 81 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 82 structure, then the returned socket address structure will be ready for a 83 call to ccoonnnneecctt() (for a connection-oriented protocol) or either 84 ccoonnnneecctt(), sseennddttoo(), or sseennddmmssgg() (for a connectionless protocol). In 85 this case, if the _n_o_d_e_n_a_m_e argument is a NULL pointer, then the IP 86 address portion of the socket address structure will be set to the loop- 87 back address. 88 89 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- 90 ture, then upon successful return the _a_i___c_a_n_o_n_n_a_m_e member of the first 91 addrinfo structure in the linked list will point to a null-terminated 92 string containing the canonical name of the specified _n_o_d_e_n_a_m_e. 93 94 If the AI_NUMERICHOST bit is set in the _a_i___f_l_a_g_s member of the _h_i_n_t_s 95 structure, then a non-NULL _n_o_d_e_n_a_m_e string must be a numeric host address 96 string. Otherwise an error of EAI_NONAME is returned. This flag pre- 97 vents any type of name resolution service (e.g., the DNS) from being 98 called. 99 100 All of the information returned by ggeettaaddddrriinnffoo() is dynamically allo- 101 cated: the addrinfo structures, and the socket address structures and 102 canonical node name strings pointed to by the addrinfo structures. To 103 return this information to the system the function Fn freeaddrinfo is 104 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, 105 along with any dynamic storage pointed to by the structure. This opera- 106 tion is repeated until a NULL _a_i___n_e_x_t pointer is encountered. 107 108 To aid applications in printing error messages based on the EAI_xxx codes 109 returned by ggeettaaddddrriinnffoo(), ggaaii__ssttrreerrrroorr() is defined. The argument is 110 one of the EAI_xxx values defined earlier and the return value points to 111 a string describing the error. If the argument is not one of the EAI_xxx 112 values, the function still returns a pointer to a string whose contents 113 indicate an unknown error. 114 115FFIILLEESS 116 /etc/hosts 117 /etc/host.conf 118 /etc/resolv.conf 119 120DDIIAAGGNNOOSSTTIICCSS 121 Error return status from ggeettaaddddrriinnffoo() is zero on success and non-zero on 122 errors. Non-zero error codes are defined in <netdb.h>, and as follows: 123 124 EAI_ADDRFAMILY address family for nodename not supported 125 EAI_AGAIN temporary failure in name resolution 126 EAI_BADFLAGS invalid value for ai_flags 127 EAI_FAIL non-recoverable failure in name resolution 128 EAI_FAMILY ai_family not supported 129 EAI_MEMORY memory allocation failure 130 EAI_NODATA no address associated with nodename 131 EAI_NONAME nodename nor servname provided, or not known 132 EAI_SERVICE servname not supported for ai_socktype 133 EAI_SOCKTYPE ai_socktype not supported 134 EAI_SYSTEM system error returned in errno 135 136 If called with proper argument, ggaaii__ssttrreerrrroorr() returns a pointer to a 137 string describing the given error code. If the argument is not one of 138 the EAI_xxx values, the function still returns a pointer to a string 139 whose contents indicate an unknown error. 140 141SSEEEE AALLSSOO 142 getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5), 143 services(5), hostname(7) 144 145 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter- 146 face Extensions for IPv6,'' RFC2133, April 1997. 147 148HHIISSTTOORRYY 149 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack 150 kit. 151 152SSTTAANNDDAARRDDSS 153 The ggeettaaddddrriinnffoo() function is defined IEEE POSIX 1003.1g draft specifica- 154 tion, and documented in ``Basic Socket Interface Extensions for IPv6'' 155 (RFC2133). 156 157BBUUGGSS 158 The text was shamelessly copied from RFC2133. 159 160KAME May 25, 1995 KAME 161