<!-- - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. - - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. --> <HTML ><HEAD ><TITLE >lwres_getaddrinfo</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.73 "></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><H1 ><A NAME="AEN1" >lwres_getaddrinfo</A ></H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN8" ></A ><H2 >Name</H2 >lwres_getaddrinfo, lwres_freeaddrinfo -- socket address structure to host and service name</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN12" ></A ><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><A NAME="AEN13" ></A ><P ></P ><PRE CLASS="FUNCSYNOPSISINFO" >#include <lwres/netdb.h></PRE ><P ><CODE ><CODE CLASS="FUNCDEF" >int lwres_getaddrinfo</CODE >(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void lwres_freeaddrinfo</CODE >(struct addrinfo *ai);</CODE ></P ><P ></P ></DIV ><P >If the operating system does not provide a <SPAN CLASS="TYPE" >struct addrinfo</SPAN >, the following structure is used: <PRE CLASS="PROGRAMLISTING" >struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ 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 hostname */ struct sockaddr *ai_addr; /* binary address */ struct addrinfo *ai_next; /* next structure in linked list */ };</PRE ></P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN29" ></A ><H2 >DESCRIPTION</H2 ><P ><TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > is used to get a list of IP addresses and port numbers for host <TT CLASS="PARAMETER" ><I >hostname</I ></TT > and service <TT CLASS="PARAMETER" ><I >servname</I ></TT >. The function is the lightweight resolver's implementation of <TT CLASS="FUNCTION" >getaddrinfo()</TT > as defined in RFC2133. <TT CLASS="PARAMETER" ><I >hostname</I ></TT > and <TT CLASS="PARAMETER" ><I >servname</I ></TT > are pointers to null-terminated strings or <SPAN CLASS="TYPE" >NULL</SPAN >. <TT CLASS="PARAMETER" ><I >hostname</I ></TT > is either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 address. <TT CLASS="PARAMETER" ><I >servname</I ></TT > is either a decimal port number or a service name as listed in <TT CLASS="FILENAME" >/etc/services</TT >.</P ><P ><TT CLASS="PARAMETER" ><I >hints</I ></TT > is an optional pointer to a <SPAN CLASS="TYPE" >struct addrinfo</SPAN >. This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in <TT CLASS="PARAMETER" ><I >*hints</I ></TT >: <P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="CONSTANT" >ai_family</TT ></DT ><DD ><P >The protocol family that should be used. When <TT CLASS="CONSTANT" >ai_family</TT > is set to <SPAN CLASS="TYPE" >PF_UNSPEC</SPAN >, it means the caller will accept any protocol family supported by the operating system.</P ></DD ><DT ><TT CLASS="CONSTANT" >ai_socktype</TT ></DT ><DD ><P >denotes the type of socket — <SPAN CLASS="TYPE" >SOCK_STREAM</SPAN >, <SPAN CLASS="TYPE" >SOCK_DGRAM</SPAN > or <SPAN CLASS="TYPE" >SOCK_RAW</SPAN > — that is wanted. When <TT CLASS="CONSTANT" >ai_socktype</TT > is zero the caller will accept any socket type.</P ></DD ><DT ><TT CLASS="CONSTANT" >ai_protocol</TT ></DT ><DD ><P >indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP. If <TT CLASS="CONSTANT" >ai_protocol</TT > is zero the caller will accept any protocol.</P ></DD ><DT ><TT CLASS="CONSTANT" >ai_flags</TT ></DT ><DD ><P >Flag bits. If the <SPAN CLASS="TYPE" >AI_CANONNAME</SPAN > bit is set, a successful call to <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > will return a a null-terminated string containing the canonical name of the specified hostname in <TT CLASS="CONSTANT" >ai_canonname</TT > of the first <SPAN CLASS="TYPE" >addrinfo</SPAN > structure returned. Setting the <SPAN CLASS="TYPE" >AI_PASSIVE</SPAN > bit indicates that the returned socket address structure is intended for used in a call to <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >bind</SPAN >(2)</SPAN >. In this case, if the hostname argument is a <SPAN CLASS="TYPE" >NULL</SPAN > pointer, then the IP address portion of the socket address structure will be set to <SPAN CLASS="TYPE" >INADDR_ANY</SPAN > for an IPv4 address or <SPAN CLASS="TYPE" >IN6ADDR_ANY_INIT</SPAN > for an IPv6 address.</P ><P >When <TT CLASS="CONSTANT" >ai_flags</TT > does not set the <SPAN CLASS="TYPE" >AI_PASSIVE</SPAN > bit, the returned socket address structure will be ready for use in a call to <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >connect</SPAN >(2)</SPAN > for a connection-oriented protocol or <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >connect</SPAN >(2)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >sendto</SPAN >(2)</SPAN >, or <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >sendmsg</SPAN >(2)</SPAN > if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if <TT CLASS="PARAMETER" ><I >hostname</I ></TT > is a <SPAN CLASS="TYPE" >NULL</SPAN > pointer and <SPAN CLASS="TYPE" >AI_PASSIVE</SPAN > is not set in <TT CLASS="CONSTANT" >ai_flags</TT >.</P ><P >If <TT CLASS="CONSTANT" >ai_flags</TT > is set to <SPAN CLASS="TYPE" >AI_NUMERICHOST</SPAN > it indicates that <TT CLASS="PARAMETER" ><I >hostname</I ></TT > should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.</P ></DD ></DL ></DIV ></P ><P >All other elements of the <SPAN CLASS="TYPE" >struct addrinfo</SPAN > passed via <TT CLASS="PARAMETER" ><I >hints</I ></TT > must be zero.</P ><P >A <TT CLASS="PARAMETER" ><I >hints</I ></TT > of <SPAN CLASS="TYPE" >NULL</SPAN > is treated as if the caller provided a <SPAN CLASS="TYPE" >struct addrinfo</SPAN > initialized to zero with <TT CLASS="CONSTANT" >ai_family</TT >set to <TT CLASS="CONSTANT" >PF_UNSPEC</TT >.</P ><P >After a successful call to <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT >, <TT CLASS="PARAMETER" ><I >*res</I ></TT > is a pointer to a linked list of one or more <SPAN CLASS="TYPE" >addrinfo</SPAN > structures. Each <SPAN CLASS="TYPE" >struct addrinfo</SPAN > in this list cn be processed by following the <TT CLASS="CONSTANT" >ai_next</TT > pointer, until a <SPAN CLASS="TYPE" >NULL</SPAN > pointer is encountered. The three members <TT CLASS="CONSTANT" >ai_family</TT >, <TT CLASS="CONSTANT" >ai_socktype</TT >, and <TT CLASS="CONSTANT" >ai_protocol</TT > in each returned <SPAN CLASS="TYPE" >addrinfo</SPAN > structure contain the corresponding arguments for a call to <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >socket</SPAN >(2)</SPAN >. For each <SPAN CLASS="TYPE" >addrinfo</SPAN > structure in the list, the <TT CLASS="CONSTANT" >ai_addr</TT > member points to a filled-in socket address structure of length <TT CLASS="CONSTANT" >ai_addrlen</TT >.</P ><P >All of the information returned by <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the <TT CLASS="CONSTANT" >addrinfo</TT >structures. Memory allocated for the dynamically allocated structures created by a successful call to <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > is released by <TT CLASS="FUNCTION" >lwres_freeaddrinfo()</TT >. <TT CLASS="PARAMETER" ><I >ai</I ></TT > is a pointer to a <SPAN CLASS="TYPE" >struct addrinfo</SPAN > created by a call to <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT >.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN142" ></A ><H2 >RETURN VALUES</H2 ><P ><TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > returns zero on success or one of the error codes listed in <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >gai_strerror</SPAN >(3)</SPAN > if an error occurs. If both <TT CLASS="PARAMETER" ><I >hostname</I ></TT > and <TT CLASS="PARAMETER" ><I >servname</I ></TT > are <SPAN CLASS="TYPE" >NULL</SPAN > <TT CLASS="FUNCTION" >lwres_getaddrinfo()</TT > returns <SPAN CLASS="ERRORCODE" >EAI_NONAME</SPAN >. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN154" ></A ><H2 >SEE ALSO</H2 ><P ><SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_getaddrinfo</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_freeaddrinfo</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_gai_strerror</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >RFC2133</SPAN ></SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >getservbyname</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >bind</SPAN >(2)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >connect</SPAN >(2)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >sendto</SPAN >(2)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >sendmsg</SPAN >(2)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >socket</SPAN >(2)</SPAN >.</P ></DIV ></BODY ></HTML >