neon
3

# neon

HTTP and WebDAV client library

## Description

neon is an HTTP and WebDAV client library. The major abstractions exposed are the HTTP session, created by ; and the HTTP request, created by . HTTP authentication is handled transparently for server and proxy servers, see ; complete SSL/TLS support is also included, see .

## Conventions

Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below.

### Thread-safeness and global initialization

&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 `getaddrinfo` interface, which &neon; supports; some others implement `gethostbyname` using thread-local storage.

To allow thread-safe use of SSL in the OpenSSL and GnuTLS libraries &neon; must be configured using the `--enable-threadsafe-ssl`; if this is done, locking callbacks will be registered by ; note that care must be exercised if &neon; is used in conjunction with another library which uses OpenSSL or GnuTLS.

Some platforms and libraries used by &neon; require global initialization before use; notably:

- The `SIGPIPE` signal disposition must be set to ignored or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer.

- OpenSSL and GnuTLS require global initialization to load shared lookup tables.

- The Win32 socket library requires initialization before use.

The 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 (and ); &neon; neither checks whether these functions are called nor calls them itself.

For some applications and configurations it may be necessary to call to initialize the support for internationalization in &neon;.

### Asynchronous signal safety

No function in &neon; is defined to be async-signal safe - 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.

### Functions using global state

Any function in &neon; may modify the `errno` global variable as a side-effect. Except where explicitly documented, the value of `errno` is unspecified after any &neon; function call.

Other than in the use of `errno`, the only functions which use or modify process-global state in &neon; are as follows:

- , , and , as described above

- `ne_debug_init` and `ne_debug`, if enabled at compile time; for debugging output

- for installing a process-global callback to be invoked on `malloc` failure

### Namespaces

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 namespace prefix. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions.

The &neon; library reserves the use of the namespace prefixes `ne_` and `NE_`. 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.

SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_

  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.

gnutls_, gcry_, gpg_

  Namespaces used by the GnuTLS library (and dependencies thereof)

XML_, Xml[A-Z]

  Namespaces used by the expat library.

xml[A-Z], html[A-Z], docb[A-Z]

  Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes.

inflate, deflate, crc32, compress, uncompres, adler32, zlib

  Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes.

krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit

  Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes.

pakchois_

  Namespace used by the pakchois library.

px_

  Namespace used by the libproxy library.

### Argument validation

&neon; does not attempt to validate that the parameters passed to functions conform to the API (for instance, checking that pointer arguments are not &null;). Any use of the &neon; API which is not documented to produce a certain behaviour results is said to produce undefined behaviour; it is likely that &neon; will segfault under these conditions.

### URI paths, WebDAV metadata

The path strings passed to any function must be URI-encoded 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.

### User interaction

As a pure library interface, &neon; will never produce output on `stdout` or `stderr`; all user interaction is the responsibilty of the application.

### Memory handling

neon does not attempt to cope gracefully with an out-of-memory situation; instead, by default, the `abort` function is called to immediately terminate the process. An application may register a custom function which will be called before `abort` in such a situation; see .

### Callbacks and userdata

Whenever a callback is registered, a `userdata` pointer is also used to allow the application to associate a context with the callback. The userdata is of type void *, allowing any pointer to be used.

### Large File Support

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 `off_t` type, where LFS support is available.

Some interfaces use the `ne_off_t` type, which is defined to be either `off_t` or `off64_t` according to whether LFS support is detected at build time. &neon; does not use or require the `-D_FILE_OFFSET_BITS=64` macro definition.

## See also

,