1<refentry id="refresolve"> 2 3 <refmeta> 4 <refentrytitle>ne_addr_resolve</refentrytitle> 5 <manvolnum>3</manvolnum> 6 </refmeta> 7 8 <refnamediv> 9 <refname id="ne_addr_resolve">ne_addr_resolve</refname> 10 <refname id="ne_addr_result">ne_addr_result</refname> 11 <refname id="ne_addr_first">ne_addr_first</refname> 12 <refname id="ne_addr_next">ne_addr_next</refname> 13 <refname id="ne_addr_error">ne_addr_error</refname> 14 <refname id="ne_addr_destroy">ne_addr_destroy</refname> 15 <refpurpose>functions to resolve hostnames to addresses</refpurpose> 16 </refnamediv> 17 18 <refsynopsisdiv> 19 20 <funcsynopsis> 21 22 <funcsynopsisinfo>#include <ne_socket.h></funcsynopsisinfo> 23 24 <funcprototype> 25 <funcdef>ne_sock_addr *<function>ne_addr_resolve</function></funcdef> 26 <paramdef>const char *<parameter>hostname</parameter></paramdef> 27 <paramdef>int <parameter>flags</parameter></paramdef> 28 </funcprototype> 29 30 <funcprototype> 31 <funcdef>int <function>ne_addr_result</function></funcdef> 32 <paramdef>const ne_sock_addr *<parameter>addr</parameter></paramdef> 33 </funcprototype> 34 35 <funcprototype> 36 <funcdef>const ne_inet_addr *<function>ne_addr_first</function></funcdef> 37 <paramdef>ne_sock_addr *<parameter>addr</parameter></paramdef> 38 </funcprototype> 39 40 <funcprototype> 41 <funcdef>const ne_inet_addr *<function>ne_addr_next</function></funcdef> 42 <paramdef>ne_sock_addr *<parameter>addr</parameter></paramdef> 43 </funcprototype> 44 45 <funcprototype> 46 <funcdef>char *<function>ne_addr_error</function></funcdef> 47 <paramdef>const ne_sock_addr *<parameter>addr</parameter></paramdef> 48 <paramdef>char *<parameter>buffer</parameter></paramdef> 49 <paramdef>size_t <parameter>bufsiz</parameter></paramdef> 50 </funcprototype> 51 52 <funcprototype> 53 <funcdef>void <function>ne_addr_destroy</function></funcdef> 54 <paramdef>ne_sock_addr *<parameter>addr</parameter></paramdef> 55 </funcprototype> 56 57 </funcsynopsis> 58 59 </refsynopsisdiv> 60 61 <refsect1> 62 <title>Description</title> 63 64 <para>The <function>ne_addr_resolve</function> function resolves 65 the given <parameter>hostname</parameter>, returning an 66 <type>ne_sock_addr</type> object representing the address (or 67 addresses) associated with the hostname. The 68 <parameter>flags</parameter> parameter is currently unused, and 69 must be passed as 0.</para> 70 71 <para>The <parameter>hostname</parameter> passed to 72 <function>ne_addr_resolve</function> can be a DNS hostname 73 (e.g. <literal>"www.example.com"</literal>) or an IPv4 dotted quad 74 (e.g. <literal>"192.0.34.72"</literal>); or, on systems which 75 support IPv6, an IPv6 hex address, which may be enclosed in 76 brackets, e.g. <literal>"[::1]"</literal>.</para> 77 78 <para>To determine whether the hostname was successfully resolved, 79 the <function>ne_addr_result</function> function is used, which 80 returns non-zero if an error occurred. If an error did occur, the 81 <function>ne_addr_error</function> function can be used, which 82 will copy the error string into a given 83 <parameter>buffer</parameter> (of size 84 <parameter>bufsiz</parameter>).</para> 85 86 <para>The functions <function>ne_addr_first</function> and 87 <function>ne_addr_next</function> are used to retrieve the 88 Internet addresses associated with an address object which has 89 been successfully resolved. <function>ne_addr_first</function> 90 returns the first address; <function>ne_addr_next</function> 91 returns the next address after the most recent call to 92 <function>ne_addr_next</function> or 93 <function>ne_addr_first</function>, or &null; if there are no more 94 addresses. The <type>ne_inet_addr</type> pointer returned by 95 these functions can be passed to 96 <function>ne_sock_connect</function> to connect a socket.</para> 97 98 <para>After the address object has been used, it should be 99 destroyed using <function>ne_addr_destroy</function>.</para> 100 101 </refsect1> 102 103 <refsect1> 104 <title>Return value</title> 105 106 <para><function>ne_addr_resolve</function> returns a pointer to an 107 address object, and never &null;. 108 <function>ne_addr_error</function> returns the 109 <parameter>buffer</parameter> parameter .</para> 110 111 </refsect1> 112 113 <refsect1> 114 <title>Examples</title> 115 116 <para>The code below prints out the set of addresses associated 117 with the hostname <literal>www.google.com</literal>.</para> 118 119 <programlisting>ne_sock_addr *addr; 120char buf[256]; 121 122addr = ne_addr_resolve("www.google.com", 0); 123if (ne_addr_result(addr)) { 124 printf("Could not resolve www.google.com: %s\n", 125 ne_addr_error(addr, buf, sizeof buf)); 126} else { 127 const ne_inet_addr *ia; 128 printf("www.google.com:"); 129 for (ia = ne_addr_first(addr); ia != NULL; ia = ne_addr_next(addr)) { 130 printf(" %s", ne_iaddr_print(ia, buf, sizeof buf)); 131 } 132 putchar('\n'); 133} 134ne_addr_destroy(addr); 135</programlisting> 136 </refsect1> 137 138 <refsect1> 139 <title>See also</title> 140 141 <para><xref linkend="ne_iaddr_print"/></para> 142 </refsect1> 143 144</refentry> 145 146