1<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.76.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" title="neon"><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" title="Description"><a name="id446181"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library. The major 2 abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>, 3 created by <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP 4 <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 5 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 6 included, see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1" title="Conventions"><a name="id446521"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to 7 provide a consistent and simple interface; these are documented 8 below.</p><div class="refsect2" title="Thread-safeness and global initialization"><a name="id446602"></a><h3>Thread-safeness and global initialization</h3><p>neon itself is implemented to be thread-safe (avoiding any 9 use of global state), but relies on the operating system providing 10 a thread-safe resolver interface. Modern operating systems offer 11 the thread-safe <code class="function">getaddrinfo</code> interface, which 12 neon supports; some others implement 13 <code class="function">gethostbyname</code> using thread-local 14 storage.</p><p>To allow thread-safe use of SSL in the OpenSSL and GnuTLS 15 libraries neon must be configured using the 16 <code class="literal">--enable-threadsafe-ssl</code>; if this is done, 17 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 18 neon is used in conjunction with another library which uses 19 OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global 20 initialization before use; notably: 21 22 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The <code class="literal">SIGPIPE</code> signal 23 disposition must be set to <span class="emphasis"><em>ignored</em></span> or 24 otherwise handled to avoid process termination when writing to a 25 socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global 26 initialization to load shared lookup 27 tables.</li><li class="listitem">The Win32 socket library requires 28 initialization before use.</li></ul></div><p> 29 30 The <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> function should be called 31 before any other use of neon to perform any necessary 32 initialization needed for the particular platform. Applications 33 wishing to perform all the necessary process-global initialization 34 steps themselves may omit to call <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> 35 (and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether 36 these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary 37 to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support 38 for internationalization in neon.</p></div><div class="refsect2" title="Asynchronous signal safety"><a name="id446695"></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> - 39 that is, no function is safe to call from a signal handler. Any 40 call into the neon library from a signal handler will have 41 undefined behaviour - in other words, it may crash the 42 process.</p></div><div class="refsect2" title="Functions using global state"><a name="id446711"></a><h3>Functions using global state</h3><p>Any function in neon may modify the 43 <code class="literal">errno</code> global variable as a side-effect. Except 44 where explicitly documented, the value of <code class="literal">errno</code> 45 is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only 46 functions which use or modify process-global state in neon are 47 as follows: 48 49 </p><div class="itemizedlist"><ul class="itemizedlist" 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 50 described above</li><li class="listitem"><code class="function">ne_debug_init</code> and 51 <code class="function">ne_debug</code>, if enabled at compile time; for 52 debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for 53 installing a process-global callback to be invoked on 54 <code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2" title="Namespaces"><a name="id446785"></a><h3>Namespaces</h3><p>To avoid possible collisions between names used for symbols 55 and preprocessor macros by an application and the libraries it 56 uses, it is good practice for each library to reserve a particular 57 <span class="emphasis"><em>namespace prefix</em></span>. An application which 58 ensures it uses no names with these prefixes is then guaranteed to 59 avoid such collisions.</p><p>The neon library reserves the use of the namespace 60 prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>. The 61 libraries used by neon may also reserve certain namespaces; 62 collisions between these libraries and a neon-based application 63 will not be detected at compile time, since the underlying library 64 interfaces are not exposed through the neon header files. Such 65 collisions can only be detected at link time, when the linker 66 attempts to resolve symbols. The following list documents some of 67 the namespaces claimed by libraries used by neon; this list may 68 be incomplete.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><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 69 library; little attempt has been made to keep exported symbols 70 within any particular prefixes for this 71 library.</td></tr><tr><td><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and 72 dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces 73 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 74 relatively small number of symbols are used without these 75 prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompres, adler32, 76 zlib</span></p></td><td>Namespaces used by the zlib library; a 77 relatively small number of symbols are used without these 78 prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, 79 mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI 80 library and dependencies thereof; a number of symbols lie 81 outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois 82 library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy 83 library.</td></tr></tbody></table></div></div><div class="refsect2" title="Argument validation"><a name="id446915"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters 84 passed to functions conform to the API (for instance, checking 85 that pointer arguments are not <code class="literal">NULL</code>). Any use of the neon API 86 which is not documented to produce a certain behaviour results is 87 said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is 88 likely that neon will segfault under these conditions.</p></div><div class="refsect2" title="URI paths, WebDAV metadata"><a name="id446928"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be 89 <span class="emphasis"><em>URI-encoded</em></span> by the application; neon never 90 performs any URI encoding or decoding internally. WebDAV property 91 names and values must be valid UTF-8 encoded Unicode 92 strings.</p></div><div class="refsect2" title="User interaction"><a name="id446952"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce 93 output on <code class="constant">stdout</code> or 94 <code class="constant">stderr</code>; all user interaction is the 95 responsibilty of the application.</p></div><div class="refsect2" title="Memory handling"><a name="id446973"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an 96 out-of-memory situation; instead, by default, the 97 <code class="function">abort</code> function is called to immediately 98 terminate the process. An application may register a custom 99 function which will be called before <code class="function">abort</code> in 100 such a situation; see <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2" title="Callbacks and userdata"><a name="id447001"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a 101 <code class="literal">userdata</code> pointer is also used to allow the 102 application to associate a context with the callback. The 103 userdata is of type <em class="type">void *</em>, allowing any pointer to 104 be used.</p></div><div class="refsect2" title="Large File Support"><a name="id447021"></a><h3>Large File Support</h3><p>Since version 0.27.0, neon transparently uses the "LFS 105 transitional" interfaces in places where file-backed file 106 descriptors are manipulated. This means files larger than 2GiB 107 can be handled on platforms with a native 32-bit 108 <code class="literal">off_t</code> type, where LFS support is 109 available.</p><p>Some interfaces use the <code class="literal">ne_off_t</code> type, 110 which is defined to be either <code class="literal">off_t</code> or 111 <code class="literal">off64_t</code> according to whether LFS support is 112 detected at build time. neon does not use or require the 113 <code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1" title="See also"><a name="id447067"></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> 114