head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.2 netbsd-11-0-RC3:1.1.1.2 netbsd-11-0-RC2:1.1.1.2 netbsd-11-0-RC1:1.1.1.2 perseant-exfatfs-base-20250801:1.1.1.2 netbsd-11:1.1.1.2.0.48 netbsd-11-base:1.1.1.2 netbsd-10-1-RELEASE:1.1.1.2 perseant-exfatfs-base-20240630:1.1.1.2 perseant-exfatfs:1.1.1.2.0.46 perseant-exfatfs-base:1.1.1.2 netbsd-8-3-RELEASE:1.1.1.2 netbsd-9-4-RELEASE:1.1.1.2 netbsd-10-0-RELEASE:1.1.1.2 netbsd-10-0-RC6:1.1.1.2 netbsd-10-0-RC5:1.1.1.2 netbsd-10-0-RC4:1.1.1.2 netbsd-10-0-RC3:1.1.1.2 netbsd-10-0-RC2:1.1.1.2 netbsd-10-0-RC1:1.1.1.2 netbsd-10:1.1.1.2.0.44 netbsd-10-base:1.1.1.2 netbsd-9-3-RELEASE:1.1.1.2 cjep_sun2x-base1:1.1.1.2 cjep_sun2x:1.1.1.2.0.42 cjep_sun2x-base:1.1.1.2 cjep_staticlib_x-base1:1.1.1.2 netbsd-9-2-RELEASE:1.1.1.2 cjep_staticlib_x:1.1.1.2.0.40 cjep_staticlib_x-base:1.1.1.2 netbsd-9-1-RELEASE:1.1.1.2 phil-wifi-20200421:1.1.1.2 phil-wifi-20200411:1.1.1.2 is-mlppp:1.1.1.2.0.38 is-mlppp-base:1.1.1.2 phil-wifi-20200406:1.1.1.2 netbsd-8-2-RELEASE:1.1.1.2 netbsd-9-0-RELEASE:1.1.1.2 netbsd-9-0-RC2:1.1.1.2 netbsd-9-0-RC1:1.1.1.2 phil-wifi-20191119:1.1.1.2 netbsd-9:1.1.1.2.0.36 netbsd-9-base:1.1.1.2 phil-wifi-20190609:1.1.1.2 netbsd-8-1-RELEASE:1.1.1.2 netbsd-8-1-RC1:1.1.1.2 pgoyette-compat-merge-20190127:1.1.1.2 pgoyette-compat-20190127:1.1.1.2 pgoyette-compat-20190118:1.1.1.2 pgoyette-compat-1226:1.1.1.2 pgoyette-compat-1126:1.1.1.2 pgoyette-compat-1020:1.1.1.2 pgoyette-compat-0930:1.1.1.2 pgoyette-compat-0906:1.1.1.2 netbsd-7-2-RELEASE:1.1.1.2 pgoyette-compat-0728:1.1.1.2 netbsd-8-0-RELEASE:1.1.1.2 phil-wifi:1.1.1.2.0.34 phil-wifi-base:1.1.1.2 pgoyette-compat-0625:1.1.1.2 netbsd-8-0-RC2:1.1.1.2 pgoyette-compat-0521:1.1.1.2 pgoyette-compat-0502:1.1.1.2 pgoyette-compat-0422:1.1.1.2 netbsd-8-0-RC1:1.1.1.2 pgoyette-compat-0415:1.1.1.2 pgoyette-compat-0407:1.1.1.2 pgoyette-compat-0330:1.1.1.2 pgoyette-compat-0322:1.1.1.2 pgoyette-compat-0315:1.1.1.2 netbsd-7-1-2-RELEASE:1.1.1.2 pgoyette-compat:1.1.1.2.0.32 pgoyette-compat-base:1.1.1.2 netbsd-7-1-1-RELEASE:1.1.1.2 matt-nb8-mediatek:1.1.1.2.0.30 matt-nb8-mediatek-base:1.1.1.2 perseant-stdc-iso10646:1.1.1.2.0.28 perseant-stdc-iso10646-base:1.1.1.2 netbsd-8:1.1.1.2.0.26 netbsd-8-base:1.1.1.2 prg-localcount2-base3:1.1.1.2 prg-localcount2-base2:1.1.1.2 prg-localcount2-base1:1.1.1.2 prg-localcount2:1.1.1.2.0.24 prg-localcount2-base:1.1.1.2 pgoyette-localcount-20170426:1.1.1.2 bouyer-socketcan-base1:1.1.1.2 pgoyette-localcount-20170320:1.1.1.2 netbsd-7-1:1.1.1.2.0.22 netbsd-7-1-RELEASE:1.1.1.2 netbsd-7-1-RC2:1.1.1.2 netbsd-7-nhusb-base-20170116:1.1.1.2 bouyer-socketcan:1.1.1.2.0.20 bouyer-socketcan-base:1.1.1.2 pgoyette-localcount-20170107:1.1.1.2 netbsd-7-1-RC1:1.1.1.2 pgoyette-localcount-20161104:1.1.1.2 netbsd-7-0-2-RELEASE:1.1.1.2 localcount-20160914:1.1.1.2 netbsd-7-nhusb:1.1.1.2.0.18 netbsd-7-nhusb-base:1.1.1.2 pgoyette-localcount-20160806:1.1.1.2 pgoyette-localcount-20160726:1.1.1.2 pgoyette-localcount:1.1.1.2.0.16 pgoyette-localcount-base:1.1.1.2 netbsd-7-0-1-RELEASE:1.1.1.2 netbsd-7-0:1.1.1.2.0.14 netbsd-7-0-RELEASE:1.1.1.2 netbsd-7-0-RC3:1.1.1.2 netbsd-7-0-RC2:1.1.1.2 netbsd-7-0-RC1:1.1.1.2 netbsd-5-2-3-RELEASE:1.1.1.1.4.2 netbsd-5-1-5-RELEASE:1.1.1.1.6.2 netbsd-6-0-6-RELEASE:1.1.1.1 netbsd-6-1-5-RELEASE:1.1.1.1 netbsd-7:1.1.1.2.0.12 netbsd-7-base:1.1.1.2 yamt-pagecache-base9:1.1.1.2 yamt-pagecache-tag8:1.1.1.1.14.1 netbsd-6-1-4-RELEASE:1.1.1.1 netbsd-6-0-5-RELEASE:1.1.1.1 tls-earlyentropy:1.1.1.2.0.10 tls-earlyentropy-base:1.1.1.2 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.2 riastradh-drm2-base3:1.1.1.2 netbsd-6-1-3-RELEASE:1.1.1.1 netbsd-6-0-4-RELEASE:1.1.1.1 netbsd-5-2-2-RELEASE:1.1.1.1.4.2 netbsd-5-1-4-RELEASE:1.1.1.1.6.2 netbsd-6-1-2-RELEASE:1.1.1.1 netbsd-6-0-3-RELEASE:1.1.1.1 netbsd-5-2-1-RELEASE:1.1.1.1.4.2 netbsd-5-1-3-RELEASE:1.1.1.1.6.2 netbsd-6-1-1-RELEASE:1.1.1.1 riastradh-drm2-base2:1.1.1.2 riastradh-drm2-base1:1.1.1.2 riastradh-drm2:1.1.1.2.0.4 riastradh-drm2-base:1.1.1.2 netbsd-6-1:1.1.1.1.0.22 netbsd-6-0-2-RELEASE:1.1.1.1 netbsd-6-1-RELEASE:1.1.1.1 khorben-n900:1.1.1.2.0.8 netbsd-6-1-RC4:1.1.1.1 netbsd-6-1-RC3:1.1.1.1 agc-symver:1.1.1.2.0.6 agc-symver-base:1.1.1.2 netbsd-6-1-RC2:1.1.1.1 netbsd-6-1-RC1:1.1.1.1 yamt-pagecache-base8:1.1.1.2 netbsd-5-2:1.1.1.1.4.2.0.2 netbsd-6-0-1-RELEASE:1.1.1.1 yamt-pagecache-base7:1.1.1.2 netbsd-5-2-RELEASE:1.1.1.1.4.2 netbsd-5-2-RC1:1.1.1.1.4.2 matt-nb6-plus-nbase:1.1.1.1 yamt-pagecache-base6:1.1.1.2 netbsd-6-0:1.1.1.1.0.20 netbsd-6-0-RELEASE:1.1.1.1 netbsd-6-0-RC2:1.1.1.1 tls-maxphys:1.1.1.2.0.2 tls-maxphys-base:1.1.1.2 libbind-6-0:1.1.1.2 matt-nb6-plus:1.1.1.1.0.18 matt-nb6-plus-base:1.1.1.1 netbsd-6-0-RC1:1.1.1.1 yamt-pagecache-base5:1.1.1.1 yamt-pagecache-base4:1.1.1.1 netbsd-6:1.1.1.1.0.16 netbsd-6-base:1.1.1.1 netbsd-5-1-2-RELEASE:1.1.1.1.6.2 netbsd-5-1-1-RELEASE:1.1.1.1.6.2 yamt-pagecache-base3:1.1.1.1 yamt-pagecache-base2:1.1.1.1 yamt-pagecache:1.1.1.1.0.14 yamt-pagecache-base:1.1.1.1 cherry-xenmp:1.1.1.1.0.12 cherry-xenmp-base:1.1.1.1 bouyer-quota2-nbase:1.1.1.1 bouyer-quota2:1.1.1.1.0.10 bouyer-quota2-base:1.1.1.1 netbsd-5-0:1.1.1.1.0.8 netbsd-5-1:1.1.1.1.0.6 netbsd-5:1.1.1.1.0.4 matt-mips64-premerge-20101231:1.1.1.1 matt-premerge-20091211:1.1.1.1 jym-xensuspend-base:1.1.1.1 jym-xensuspend:1.1.1.1.0.2 jym-xensuspend-nbase:1.1.1.1 libbind-6-0rc1:1.1.1.1 ISC:1.1.1; locks; strict; comment @# @; 1.1 date 2009.04.12.15.33.27; author christos; state Exp; branches 1.1.1.1; next ; 1.1.1.1 date 2009.04.12.15.33.27; author christos; state Exp; branches 1.1.1.1.2.1 1.1.1.1.4.1 1.1.1.1.6.1 1.1.1.1.8.1 1.1.1.1.14.1; next 1.1.1.2; 1.1.1.2 date 2012.09.09.16.07.44; author christos; state Exp; branches; next ; 1.1.1.1.2.1 date 2009.04.12.15.33.27; author jym; state dead; branches; next 1.1.1.1.2.2; 1.1.1.1.2.2 date 2009.05.13.18.52.06; author jym; state Exp; branches; next ; 1.1.1.1.4.1 date 2009.04.12.15.33.27; author riz; state dead; branches; next 1.1.1.1.4.2; 1.1.1.1.4.2 date 2011.01.06.21.42.12; author riz; state Exp; branches; next ; 1.1.1.1.6.1 date 2009.04.12.15.33.27; author riz; state dead; branches; next 1.1.1.1.6.2; 1.1.1.1.6.2 date 2011.01.09.20.42.48; author riz; state Exp; branches; next ; 1.1.1.1.8.1 date 2009.04.12.15.33.27; author riz; state dead; branches; next 1.1.1.1.8.2; 1.1.1.1.8.2 date 2011.01.10.00.40.49; author riz; state Exp; branches; next ; 1.1.1.1.14.1 date 2012.10.30.18.55.18; author yamt; state Exp; branches; next ; desc @@ 1.1 log @Initial revision @ text @GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3) NNAAMMEE ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation in protocol-independent manner SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _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 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 argument 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 pointer, 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 address 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 loop‐ back address. 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 allo‐ cated: the addrinfo structures, and the socket address structures and canonical 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 opera‐ tion is repeated 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 , 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) 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 KAME @ 1.1.1.1 log @from ftp:///ftp.isc.org/isc/libbind import 6.0rc1. @ text @@ 1.1.1.1.14.1 log @sync with head @ text @d1 1 a1 1 GETADDRINFO(3) FreeBSD Library Functions Manual GETADDRINFO(3) d4 1 a4 1 ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr -- nodename-to-address translation d13 1 a13 1 _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); d43 1 a43 1 are specified. In the normal server scenario, only the _s_e_r_v_n_a_m_e is spec- d66 2 a67 2 structures is returned through the final argument. The caller can process each addrinfo structure in this list by following the _a_i___n_e_x_t d74 1 a74 1 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- d86 1 a86 1 address portion of the socket address structure will be set to the loop- d89 1 a89 1 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- d96 1 a96 1 string. Otherwise an error of EAI_NONAME is returned. This flag pre- d100 1 a100 1 All of the information returned by ggeettaaddddrriinnffoo() is dynamically allo- d105 1 a105 1 along with any dynamic storage pointed to by the structure. This opera- d145 2 a146 2 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter- face Extensions for IPv6,'' RFC2133, April 1997. d153 2 a154 2 The ggeettaaddddrriinnffoo() function is defined IEEE POSIX 1003.1g draft specifica- tion, and documented in ``Basic Socket Interface Extensions for IPv6'' @ 1.1.1.2 log @from ftp.isc.org @ text @d1 1 a1 1 GETADDRINFO(3) FreeBSD Library Functions Manual GETADDRINFO(3) d4 1 a4 1 ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr -- nodename-to-address translation d13 1 a13 1 _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); d43 1 a43 1 are specified. In the normal server scenario, only the _s_e_r_v_n_a_m_e is spec- d66 2 a67 2 structures is returned through the final argument. The caller can process each addrinfo structure in this list by following the _a_i___n_e_x_t d74 1 a74 1 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- d86 1 a86 1 address portion of the socket address structure will be set to the loop- d89 1 a89 1 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- d96 1 a96 1 string. Otherwise an error of EAI_NONAME is returned. This flag pre- d100 1 a100 1 All of the information returned by ggeettaaddddrriinnffoo() is dynamically allo- d105 1 a105 1 along with any dynamic storage pointed to by the structure. This opera- d145 2 a146 2 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter- face Extensions for IPv6,'' RFC2133, April 1997. d153 2 a154 2 The ggeettaaddddrriinnffoo() function is defined IEEE POSIX 1003.1g draft specifica- tion, and documented in ``Basic Socket Interface Extensions for IPv6'' @ 1.1.1.1.8.1 log @file getaddrinfo.cat3 was added on branch netbsd-5-0 on 2011-01-10 00:40:49 +0000 @ text @d1 160 @ 1.1.1.1.8.2 log @Apply patches (requested by spz in ticket #1517): Update bind to 9.7.2-P3. @ text @a0 160 GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3) NNAAMMEE ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation in protocol-independent manner SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _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 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 argument 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 pointer, 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 address 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 loop‐ back address. 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 allo‐ cated: the addrinfo structures, and the socket address structures and canonical 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 opera‐ tion is repeated 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 , 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) 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 KAME @ 1.1.1.1.6.1 log @file getaddrinfo.cat3 was added on branch netbsd-5-1 on 2011-01-09 20:42:48 +0000 @ text @d1 160 @ 1.1.1.1.6.2 log @Apply patches (requested by spz in ticket #1517): Update bind to 9.7.2-P3. @ text @a0 160 GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3) NNAAMMEE ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation in protocol-independent manner SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _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 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 argument 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 pointer, 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 address 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 loop‐ back address. 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 allo‐ cated: the addrinfo structures, and the socket address structures and canonical 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 opera‐ tion is repeated 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 , 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) 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 KAME @ 1.1.1.1.4.1 log @file getaddrinfo.cat3 was added on branch netbsd-5 on 2011-01-06 21:42:12 +0000 @ text @d1 160 @ 1.1.1.1.4.2 log @Apply patches (requested by spz in ticket #1517): Update bind to 9.7.2-P3. @ text @a0 160 GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3) NNAAMMEE ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation in protocol-independent manner SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _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 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 argument 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 pointer, 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 address 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 loop‐ back address. 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 allo‐ cated: the addrinfo structures, and the socket address structures and canonical 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 opera‐ tion is repeated 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 , 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) 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 KAME @ 1.1.1.1.2.1 log @file getaddrinfo.cat3 was added on branch jym-xensuspend on 2009-05-13 18:52:06 +0000 @ text @d1 160 @ 1.1.1.1.2.2 log @Sync with HEAD. Second commit. See http://mail-index.netbsd.org/source-changes/2009/05/13/msg221222.html @ text @a0 160 GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3) NNAAMMEE ggeettaaddddrriinnffoo ffrreeeeaaddddrriinnffoo, ggaaii__ssttrreerrrroorr - nodename-to-address translation in protocol-independent manner SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _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 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 argument 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 pointer, 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 address 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 loop‐ back address. 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 allo‐ cated: the addrinfo structures, and the socket address structures and canonical 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 opera‐ tion is repeated 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 , 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) 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 KAME @