Debian Codegraph @

deps/libneon/doc/ref/neon.xml

raw
1 <refentry id="refneon">
2
3 <refmeta>
4 <refentrytitle>neon</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname>neon</refname>
10 <refpurpose>HTTP and WebDAV client library</refpurpose>
11 </refnamediv>
12
13 <refsect1>
14 <title>Description</title>
15
16 <para>neon is an HTTP and WebDAV client library. The major
17 abstractions exposed are the HTTP <emphasis>session</emphasis>,
18 created by <xref linkend="ne_session_create"/>; and the HTTP
19 <emphasis>request</emphasis>, created by <xref
20 linkend="ne_request_create"/>. HTTP authentication is handled
21 transparently for server and proxy servers, see <xref
22 linkend="ne_set_server_auth"/>; complete SSL/TLS support is also
23 included, see <xref linkend="ne_ssl_set_verify"/>.</para>
24
25 </refsect1>
26
27 <refsect1>
28 <title>Conventions</title>
29
30 <para>Some conventions are used throughout the neon API, to
31 provide a consistent and simple interface; these are documented
32 below.</para>
33
34 <refsect2>
35 <title>Thread-safeness and global initialization</title>
36
37 <para>&neon; itself is implemented to be thread-safe (avoiding any
38 use of global state), but relies on the operating system providing
39 a thread-safe resolver interface. Modern operating systems offer
40 the thread-safe <function>getaddrinfo</function> interface, which
41 &neon; supports; some others implement
42 <function>gethostbyname</function> using thread-local
43 storage.</para>
44
45 <para>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
46 libraries &neon; must be configured using the
47 <literal>--enable-threadsafe-ssl</literal>; if this is done,
48 locking callbacks will be registered by <xref
49 linkend="ne_sock_init"/>; note that care must be exercised if
50 &neon; is used in conjunction with another library which uses
51 OpenSSL or GnuTLS.</para>
52
53 <para>Some platforms and libraries used by &neon; require global
54 initialization before use; notably:
55
56 <itemizedlist>
57 <listitem><simpara>The <literal>SIGPIPE</literal> signal
58 disposition must be set to <emphasis>ignored</emphasis> or
59 otherwise handled to avoid process termination when writing to a
60 socket which has been shutdown by the peer.</simpara></listitem>
61
62 <listitem><simpara>OpenSSL and GnuTLS require global
63 initialization to load shared lookup
64 tables.</simpara></listitem>
65
66 <listitem><simpara>The Win32 socket library requires
67 initialization before use.</simpara></listitem>
68 </itemizedlist>
69
70 The <xref linkend="ne_sock_init"/> function should be called
71 before any other use of &neon; to perform any necessary
72 initialization needed for the particular platform. Applications
73 wishing to perform all the necessary process-global initialization
74 steps themselves may omit to call <xref linkend="ne_sock_init"/>
75 (and <xref linkend="ne_sock_exit"/>); &neon; neither checks whether
76 these functions are called nor calls them itself.</para>
77
78 <para>For some applications and configurations it may be necessary
79 to call <xref linkend="ne_i18n_init"/> to initialize the support
80 for internationalization in &neon;.</para>
81
82 </refsect2>
83
84 <refsect2>
85 <title>Asynchronous signal safety</title>
86
87 <para>No function in &neon; is defined to be <quote>async-signal safe</quote> -
88 that is, no function is safe to call from a signal handler. Any
89 call into the &neon; library from a signal handler will have
90 undefined behaviour - in other words, it may crash the
91 process.</para>
92 </refsect2>
93
94 <refsect2>
95 <title>Functions using global state</title>
96
97 <para>Any function in &neon; may modify the
98 <literal>errno</literal> global variable as a side-effect. Except
99 where explicitly documented, the value of <literal>errno</literal>
100 is unspecified after any &neon; function call.</para>
101
102 <para>Other than in the use of <literal>errno</literal>, the only
103 functions which use or modify process-global state in &neon; are
104 as follows:
105
106 <itemizedlist>
107 <listitem><simpara><xref linkend="ne_sock_init"/>, <xref
108 linkend="ne_i18n_init"/>, and <xref linkend="ne_sock_exit"/>, as
109 described above</simpara></listitem>
110
111 <listitem><simpara><function>ne_debug_init</function> and
112 <function>ne_debug</function>, if enabled at compile time; for
113 debugging output</simpara></listitem>
114
115 <listitem><simpara><xref linkend="ne_oom_callback"/> for
116 installing a process-global callback to be invoked on
117 <function>malloc</function> failure</simpara></listitem>
118
119 </itemizedlist></para>
120
121 </refsect2>
122
123 <refsect2>
124 <title>Namespaces</title>
125
126 <para>To avoid possible collisions between names used for symbols
127 and preprocessor macros by an application and the libraries it
128 uses, it is good practice for each library to reserve a particular
129 <emphasis>namespace prefix</emphasis>. An application which
130 ensures it uses no names with these prefixes is then guaranteed to
131 avoid such collisions.</para>
132
133 <para>The &neon; library reserves the use of the namespace
134 prefixes <literal>ne_</literal> and <literal>NE_</literal>. The
135 libraries used by &neon; may also reserve certain namespaces;
136 collisions between these libraries and a &neon;-based application
137 will not be detected at compile time, since the underlying library
138 interfaces are not exposed through the &neon; header files. Such
139 collisions can only be detected at link time, when the linker
140 attempts to resolve symbols. The following list documents some of
141 the namespaces claimed by libraries used by &neon;; this list may
142 be incomplete.</para>
143
144 <variablelist>
145
146 <varlistentry>
147 <term>SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</term>
148 <listitem><simpara>Some of the many prefixes used by the OpenSSL
149 library; little attempt has been made to keep exported symbols
150 within any particular prefixes for this
151 library.</simpara></listitem>
152 </varlistentry>
153
154 <varlistentry>
155 <term>gnutls_, gcry_, gpg_</term>
156 <listitem><simpara>Namespaces used by the GnuTLS library (and
157 dependencies thereof)</simpara></listitem>
158 </varlistentry>
159
160 <varlistentry>
161 <term>XML_, Xml[A-Z]</term> <listitem><simpara>Namespaces
162 used by the expat library.</simpara></listitem>
163 </varlistentry>
164
165 <varlistentry>
166 <term>xml[A-Z], html[A-Z], docb[A-Z]</term>
167 <listitem><simpara>Namespaces used by the libxml2 library; a
168 relatively small number of symbols are used without these
169 prefixes.</simpara></listitem>
170 </varlistentry>
171
172 <varlistentry>
173 <term>inflate, deflate, crc32, compress, uncompres, adler32,
174 zlib</term>
175 <listitem><simpara>Namespaces used by the zlib library; a
176 relatively small number of symbols are used without these
177 prefixes.</simpara></listitem>
178 </varlistentry>
179
180 <varlistentry>
181 <term>krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
182 mit</term>
183
184 <listitem><simpara>Some of the prefixes used by the MIT GSSAPI
185 library and dependencies thereof; a number of symbols lie
186 outside these prefixes.</simpara></listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term>pakchois_</term>
191 <listitem><simpara>Namespace used by the pakchois
192 library.</simpara></listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term>px_</term>
197 <listitem><simpara>Namespace used by the libproxy
198 library.</simpara></listitem>
199 </varlistentry>
200
201 </variablelist>
202
203 </refsect2>
204
205 <refsect2>
206 <title>Argument validation</title>
207
208 <para>&neon; does not attempt to validate that the parameters
209 passed to functions conform to the API (for instance, checking
210 that pointer arguments are not &null;). Any use of the &neon; API
211 which is not documented to produce a certain behaviour results is
212 said to produce <emphasis>undefined behaviour</emphasis>; it is
213 likely that &neon; will segfault under these conditions.</para>
214
215 </refsect2>
216
217 <refsect2>
218 <title>URI paths, WebDAV metadata</title>
219
220 <para>The path strings passed to any function must be
221 <emphasis>URI-encoded</emphasis> by the application; &neon; never
222 performs any URI encoding or decoding internally. WebDAV property
223 names and values must be valid UTF-8 encoded Unicode
224 strings.</para>
225
226 </refsect2>
227
228 <refsect2>
229 <title>User interaction</title>
230
231 <para>As a pure library interface, &neon; will never produce
232 output on <constant>stdout</constant> or
233 <constant>stderr</constant>; all user interaction is the
234 responsibilty of the application.</para>
235 </refsect2>
236
237 <refsect2>
238 <title>Memory handling</title>
239
240 <para>neon does not attempt to cope gracefully with an
241 out-of-memory situation; instead, by default, the
242 <function>abort</function> function is called to immediately
243 terminate the process. An application may register a custom
244 function which will be called before <function>abort</function> in
245 such a situation; see <xref linkend="ne_oom_callback"/>.</para>
246
247 </refsect2>
248
249 <refsect2>
250 <title>Callbacks and userdata</title>
251
252 <para>Whenever a callback is registered, a
253 <literal>userdata</literal> pointer is also used to allow the
254 application to associate a context with the callback. The
255 userdata is of type <type>void *</type>, allowing any pointer to
256 be used.</para>
257
258 </refsect2>
259
260 <refsect2>
261 <title>Large File Support</title>
262
263 <para>Since version 0.27.0, &neon; transparently uses the "LFS
264 transitional" interfaces in places where file-backed file
265 descriptors are manipulated. This means files larger than 2GiB
266 can be handled on platforms with a native 32-bit
267 <literal>off_t</literal> type, where LFS support is
268 available.</para>
269
270 <para>Some interfaces use the <literal>ne_off_t</literal> type,
271 which is defined to be either <literal>off_t</literal> or
272 <literal>off64_t</literal> according to whether LFS support is
273 detected at build time. &neon; does not use or require the
274 <literal>-D_FILE_OFFSET_BITS=64</literal> macro definition.</para>
275
276 </refsect2>
277
278 </refsect1>
279
280 <refsect1>
281 <title>See also</title>
282
283 <para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para>
284 </refsect1>
285
286 </refentry>
287