Manual Pages for UNIX Operating System command usage for man neon
neon API reference NEON(3)
NAME
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
ne_session_create; and the HTTP request, 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.
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 ne_sock_init; 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:
+o 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.
+o OpenSSL and GnuTLS require global initialization to load
shared lookup tables.
+o The Win32 socket library requires initialization before
use.
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.
neon 0.29.0 Last change: 13 September 2009 1
neon API reference NEON(3)
For some applications and configurations it may be necessary
to call ne_i18n_init 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:
+o ne_sock_init, ne_i18n_init, and ne_sock_exit, as
described above
+o ne_debug_init and ne_debug, if enabled at compile time;
for debugging output
+o ne_oom_callback 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.
neon 0.29.0 Last change: 13 September 2009 2
neon API reference NEON(3)
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
ne_oom_callback.
neon 0.29.0 Last change: 13 September 2009 3
neon API reference NEON(3)
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
ne_session_create(3), ne_oom_callback
AUTHOR
Joe Orton
Author.
COPYRIGHT
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
_______________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE|
|____________________|__________________|_
| Availability | library/neon |
|____________________|__________________|_
| Interface Stability| Volatile |
|____________________|_________________|
NOTES
Source for Neon is available on http://opensolaris.org.
neon 0.29.0 Last change: 13 September 2009 4