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 &lt;ne_socket.h&gt;</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