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 288