Debian Codegraph @

deps/libneon/doc/ref/iaddr.xml

raw
1 <refentry id="refiaddr">
2
3 <refmeta>
4 <refentrytitle>ne_iaddr_make</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname id="ne_iaddr_make">ne_iaddr_make</refname>
10 <refname id="ne_iaddr_cmp">ne_iaddr_cmp</refname>
11 <refname id="ne_iaddr_print">ne_iaddr_print</refname>
12 <refname id="ne_iaddr_typeof">ne_iaddr_typeof</refname>
13 <refname id="ne_iaddr_parse">ne_iaddr_parse</refname>
14 <refname id="ne_iaddr_raw">ne_iaddr_raw</refname>
15 <refname id="ne_iaddr_reverse">ne_iaddr_reverse</refname>
16 <refname id="ne_iaddr_free">ne_iaddr_free</refname>
17 <refpurpose>functions to manipulate network addresses</refpurpose>
18 </refnamediv>
19
20 <refsynopsisdiv>
21
22 <funcsynopsis>
23
24 <funcsynopsisinfo>#include &lt;ne_socket.h&gt;
25
26 typedef enum {
27 ne_iaddr_ipv4 = 0,
28 ne_iaddr_ipv6
29 } <type>ne_iaddr_type</type>;</funcsynopsisinfo>
30
31 <funcprototype>
32 <funcdef>ne_inet_addr *<function>ne_iaddr_make</function></funcdef>
33 <paramdef>ne_iaddr_type <parameter>type</parameter></paramdef>
34 <paramdef>const unsigned char *<parameter>raw</parameter></paramdef>
35 </funcprototype>
36
37 <funcprototype>
38 <funcdef>int <function>ne_iaddr_cmp</function></funcdef>
39 <paramdef>const ne_inet_addr *<parameter>ia1</parameter></paramdef>
40 <paramdef>const ne_inet_addr *<parameter>ia2</parameter></paramdef>
41 </funcprototype>
42
43 <funcprototype>
44 <funcdef>char *<function>ne_iaddr_print</function></funcdef>
45 <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
46 <paramdef>char *<parameter>buffer</parameter></paramdef>
47 <paramdef>size_t <parameter>bufsiz</parameter></paramdef>
48 </funcprototype>
49
50 <funcprototype>
51 <funcdef>ne_iaddr_type <function>ne_iaddr_typeof</function></funcdef>
52 <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
53 </funcprototype>
54
55 <funcprototype>
56 <funcdef>ne_inet_addr *<function>ne_iaddr_parse</function></funcdef>
57 <paramdef>const char *<parameter>address</parameter></paramdef>
58 <paramdef>ne_iaddr_type <parameter>type</parameter></paramdef>
59 </funcprototype>
60
61 <funcprototype>
62 <funcdef>unsigned char *<function>ne_iaddr_raw</function></funcdef>
63 <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
64 <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
65 </funcprototype>
66
67 <funcprototype>
68 <funcdef>int <function>ne_iaddr_reverse</function></funcdef>
69 <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
70 <paramdef>char *<parameter>buffer</parameter></paramdef>
71 <paramdef>size_t <parameter>buflen</parameter></paramdef>
72 </funcprototype>
73
74 <funcprototype>
75 <funcdef>void <function>ne_iaddr_free</function></funcdef>
76 <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
77 </funcprototype>
78
79 </funcsynopsis>
80
81 </refsynopsisdiv>
82
83 <refsect1>
84 <title>Description</title>
85
86 <para><function>ne_iaddr_make</function> creates an
87 <type>ne_inet_addr</type> object from a raw binary network
88 address; for instance the four bytes <literal>0x7f 0x00 0x00
89 0x01</literal> represent the IPv4 address
90 <literal>127.0.0.1</literal>. The object returned is suitable for
91 passing to <function>ne_sock_connect</function>. A binary IPv4
92 address contains four bytes; a binary IPv6 address contains
93 sixteen bytes; addresses passed must be in network byte
94 order.</para>
95
96 <para><function>ne_iaddr_cmp</function> compares two network
97 address objects; returning zero only if they are identical. The
98 objects need not have the same address type; if the addresses are
99 not of the same type, the return value is guaranteed to be
100 non-zero.</para>
101
102 <para><function>ne_iaddr_print</function> prints a human-readable
103 string representation of a network address into a buffer, for
104 instance the string <literal>"127.0.0.1"</literal>.</para>
105
106 <para><function>ne_iaddr_typeof</function> returns the type of the
107 given network address object.</para>
108
109 <para><function>ne_iaddr_parse</function> parses a string
110 representation of a network address (such as
111 <literal>"127.0.0.1"</literal> and creates a network address
112 object to represent the parsed address.</para>
113
114 <para><function>ne_iaddr_raw</function> writes the raw byte
115 representation of a network address to the provided buffer. The
116 bytes are written in network byte order; the buffer must be of
117 suitable length for the type of address (4 bytes for an IPv4
118 address, 16 bytes for an IPv6 address).</para>
119
120 <para><function>ne_iaddr_reverse</function> performs a reverse
121 name lookup on the address object, writing the (first) hostname
122 associated with the IP address to the provided buffer. If the
123 hostname is longer than the buffer it will be silently truncated;
124 on success the string written to the buffer is always
125 &nul;-terminated.</para>
126
127 <para><function>ne_iaddr_free</function> releases the memory
128 associated with a network address object.</para>
129
130 </refsect1>
131
132 <refsect1>
133 <title>Return value</title>
134
135 <para><function>ne_iaddr_make</function> returns &null; if the
136 address type passed is not supported (for instance on a platform
137 which does not support IPv6).</para>
138
139 <para><function>ne_iaddr_print</function> returns the
140 <parameter>buffer</parameter> pointer, and never &null;.</para>
141
142 <para><function>ne_iaddr_parse</function> returns a network
143 address object on success, or &null; on failure to parse the
144 <parameter>address</parameter> parameter.</para>
145
146 <para><function>ne_iaddr_reverse</function> returns zero on
147 success or non-zero if no hostname is associated with the
148 address.</para>
149
150 <para><function>ne_iaddr_raw</function> returns the
151 <parameter>buffer</parameter> parameter, and never &null;.</para>
152
153 </refsect1>
154
155 <refsect1>
156 <title>Examples</title>
157
158 <para>The following example connects a socket to port 80 at the
159 address <literal>127.0.0.1</literal>.</para>
160
161 <programlisting>unsigned char addr[] = "\0x7f\0x00\0x00\0x01";
162 ne_inet_addr *ia;
163
164 ia = ne_iaddr_make(ne_iaddr_ipv4, addr);
165 if (ia != NULL) {
166 ne_socket *sock = ne_sock_connect(ia, 80);
167 ne_iaddr_free(ia);
168 /* ... */
169 } else {
170 /* ... */
171 }</programlisting>
172
173 </refsect1>
174
175 <refsect1>
176 <title>See also</title>
177
178 <para><xref linkend="ne_addr_resolve"/></para>
179 </refsect1>
180
181 </refentry>
182