Debian Codegraph @

deps/libneon/doc/ref/resolve.xml

raw
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;
120 char buf[256];
121
122 addr = ne_addr_resolve("www.google.com", 0);
123 if (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 }
134 ne_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