Edit File: refneon.html
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon</title><link rel="stylesheet" type="text/css" href="../manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="ref.html" title="neon API reference"><link rel="next" href="refconfig.html" title="neon-config"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">neon</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="refneon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>neon — HTTP and WebDAV client library</p></div><div class="refsect1"><a name="idm140368851469392"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library. The major abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>, created by <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP <span class="emphasis"><em>request</em></span>, created by <a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>. HTTP authentication is handled transparently for server and proxy servers, see <a class="xref" href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also included, see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1"><a name="idm140368851464416"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below.</p><div class="refsect2"><a name="idm140368851463248"></a><h3>Thread-safeness and global initialization</h3><p>neon itself is implemented to be thread-safe (avoiding any use of global state), but relies on the operating system providing a thread-safe resolver interface. Modern operating systems offer the thread-safe <code class="function">getaddrinfo</code> interface, which neon supports; some others implement <code class="function">gethostbyname</code> using thread-local storage.</p><p>To allow thread-safe use of SSL in the OpenSSL and GnuTLS libraries neon must be configured using the <code class="literal">--enable-threadsafe-ssl</code>; if this is done, locking callbacks will be registered by <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>; note that care must be exercised if neon is used in conjunction with another library which uses OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global initialization before use; notably: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">The <code class="literal">SIGPIPE</code> signal disposition must be set to <span class="emphasis"><em>ignored</em></span> or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global initialization to load shared lookup tables.</li><li class="listitem">The Win32 socket library requires initialization before use.</li></ul></div><p> The <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> function should be called before any other use of neon to perform any necessary initialization needed for the particular platform. Applications wishing to perform all the necessary process-global initialization steps themselves may omit to call <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> (and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support for internationalization in neon.</p></div><div class="refsect2"><a name="idm140368851410560"></a><h3>Asynchronous signal safety</h3><p>No function in neon is defined to be <span class="quote">“<span class="quote">async-signal safe</span>”</span> - that is, no function is safe to call from a signal handler. Any call into the neon library from a signal handler will have undefined behaviour - in other words, it may crash the process.</p></div><div class="refsect2"><a name="idm140368851408688"></a><h3>Functions using global state</h3><p>Any function in neon may modify the <code class="literal">errno</code> global variable as a side-effect. Except where explicitly documented, the value of <code class="literal">errno</code> is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only functions which use or modify process-global state in neon are as follows: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>, <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a>, and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>, as described above</li><li class="listitem"><code class="function">ne_debug_init</code> and <code class="function">ne_debug</code>, if enabled at compile time; for debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for installing a process-global callback to be invoked on <code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2"><a name="idm140368851399744"></a><h3>Namespaces</h3><p>To avoid possible collisions between names used for symbols and preprocessor macros by an application and the libraries it uses, it is good practice for each library to reserve a particular <span class="emphasis"><em>namespace prefix</em></span>. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions.</p><p>The neon library reserves the use of the namespace prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>. The libraries used by neon may also reserve certain namespaces; collisions between these libraries and a neon-based application will not be detected at compile time, since the underlying library interfaces are not exposed through the neon header files. Such collisions can only be detected at link time, when the linker attempts to resolve symbols. The following list documents some of the namespaces claimed by libraries used by neon; this list may be incomplete.</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top"><col></colgroup><tbody><tr><td><p><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></p></td><td>Some of the many prefixes used by the OpenSSL library; little attempt has been made to keep exported symbols within any particular prefixes for this library.</td></tr><tr><td><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces used by the expat library.</td></tr><tr><td><p><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></p></td><td>Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompres, adler32, zlib</span></p></td><td>Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy library.</td></tr></tbody></table></div></div><div class="refsect2"><a name="idm140368851384144"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters passed to functions conform to the API (for instance, checking that pointer arguments are not <code class="literal">NULL</code>). Any use of the neon API which is not documented to produce a certain behaviour results is said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is likely that neon will segfault under these conditions.</p></div><div class="refsect2"><a name="idm140368851380992"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be <span class="emphasis"><em>URI-encoded</em></span> by the application; neon never performs any URI encoding or decoding internally. WebDAV property names and values must be valid UTF-8 encoded Unicode strings.</p></div><div class="refsect2"><a name="idm140368851379200"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce output on <code class="constant">stdout</code> or <code class="constant">stderr</code>; all user interaction is the responsibilty of the application.</p></div><div class="refsect2"><a name="idm140368851376816"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an out-of-memory situation; instead, by default, the <code class="function">abort</code> function is called to immediately terminate the process. An application may register a custom function which will be called before <code class="function">abort</code> in such a situation; see <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2"><a name="idm140368851373296"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a <code class="literal">userdata</code> pointer is also used to allow the application to associate a context with the callback. The userdata is of type <em class="type">void *</em>, allowing any pointer to be used.</p></div><div class="refsect2"><a name="idm140368851370848"></a><h3>Large File Support</h3><p>Since version 0.27.0, neon transparently uses the "LFS transitional" interfaces in places where file-backed file descriptors are manipulated. This means files larger than 2GiB can be handled on platforms with a native 32-bit <code class="literal">off_t</code> type, where LFS support is available.</p><p>Some interfaces use the <code class="literal">ne_off_t</code> type, which is defined to be either <code class="literal">off_t</code> or <code class="literal">off64_t</code> according to whether LFS support is detected at build time. neon does not use or require the <code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1"><a name="idm140368851365408"></a><h2>See also</h2><p><a class="xref" href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon API reference </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon-config</td></tr></table></div></body></html>