neon - HTTP and WebDAV client library
neon is an HTTP and WebDAV client library. The major abstractions exposed are
the HTTP session
, created by ne_session_create; and the HTTP
, created by ne_request_create. HTTP authentication is handled
transparently for server and proxy servers, see ne_set_server_auth; complete
SSL/TLS support is also included, see ne_ssl_set_verify.
Some conventions are used throughout the neon API, to provide a consistent and
simple interface; these are documented below.
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
which neon supports; some others implement gethostbyname
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 ne_sock_init; note that care must be exercised
if neon is used in conjunction with another library which uses OpenSSL or
Some platforms and libraries used by neon require global initialization before
•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
The ne_sock_init 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 ne_sock_init (and
ne_sock_exit); neon neither checks whether these functions are called nor
calls them itself.
For some applications and configurations it may be necessary to call
ne_i18n_init to initialize the support for internationalization in neon.
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.
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:
•ne_sock_init, ne_i18n_init, and ne_sock_exit, as
•ne_debug_init and ne_debug, if
enabled at compile time; for debugging output
•ne_oom_callback for installing a process-global
callback to be invoked on malloc failure
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
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
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.
Namespace used by the pakchois library.
Namespace used by the libproxy library.
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.
The path strings passed to any function must be URI-encoded
application; neon never performs any URI encoding or decoding internally.
WebDAV property names and values must be valid UTF-8 encoded Unicode strings.
As a pure library interface, neon will never produce output on stdout
; all user interaction is the responsibilty of the application.
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 ne_oom_callback.
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
, allowing any pointer to be used.
Since version 0.27.0, neon transparently uses the "LFS transitional"
interfaces in functions which use file descriptors. This allows use of files
larger than 2GiB on platforms with a native 32-bit off_t type, where LFS
support is available.
Some neon 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.