258 lines
8.2 KiB
Plaintext
258 lines
8.2 KiB
Plaintext
'\" t
|
|
.\" Title: neon
|
|
.\" Author:
|
|
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
|
.\" Date: 14 October 2010
|
|
.\" Manual: neon API reference
|
|
.\" Source: neon 0.29.5
|
|
.\" Language: English
|
|
.\"
|
|
.TH "NEON" "3" "14 October 2010" "neon 0.29.5" "neon API reference"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
neon \- HTTP and WebDAV client library
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
neon is an HTTP and WebDAV client library\&. The major abstractions exposed are the HTTP
|
|
\fIsession\fR, created by
|
|
ne_session_create; and the HTTP
|
|
\fIrequest\fR, 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\&.
|
|
.SH "CONVENTIONS"
|
|
.PP
|
|
Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below\&.
|
|
.SS "Thread\-safeness and global initialization"
|
|
.PP
|
|
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
|
|
\fBgetaddrinfo\fR
|
|
interface, which neon supports; some others implement
|
|
\fBgethostbyname\fR
|
|
using thread\-local storage\&.
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
Some platforms and libraries used by neon require global initialization before use; notably:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
The
|
|
SIGPIPE
|
|
signal disposition must be set to
|
|
\fIignored\fR
|
|
or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
OpenSSL and GnuTLS require global initialization to load shared lookup tables\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
The Win32 socket library requires initialization before use\&.
|
|
.RE
|
|
.sp
|
|
.RE
|
|
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\&.
|
|
.PP
|
|
For some applications and configurations it may be necessary to call
|
|
ne_i18n_init
|
|
to initialize the support for internationalization in neon\&.
|
|
.SS "Asynchronous signal safety"
|
|
.PP
|
|
No function in neon is defined to be
|
|
\(lqasync\-signal safe\(rq
|
|
\- 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\&.
|
|
.SS "Functions using global state"
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
Other than in the use of
|
|
errno, the only functions which use or modify process\-global state in neon are as follows:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
ne_sock_init,
|
|
ne_i18n_init, and
|
|
ne_sock_exit, as described above
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBne_debug_init\fR
|
|
and
|
|
\fBne_debug\fR, if enabled at compile time; for debugging output
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
ne_oom_callback
|
|
for installing a process\-global callback to be invoked on
|
|
\fBmalloc\fR
|
|
failure
|
|
.RE
|
|
.SS "Namespaces"
|
|
.PP
|
|
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
|
|
\fInamespace prefix\fR\&. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions\&.
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
gnutls_, gcry_, gpg_
|
|
.RS 4
|
|
Namespaces used by the GnuTLS library (and dependencies thereof)
|
|
.RE
|
|
.PP
|
|
XML_, Xml[A\-Z]
|
|
.RS 4
|
|
Namespaces used by the expat library\&.
|
|
.RE
|
|
.PP
|
|
xml[A\-Z], html[A\-Z], docb[A\-Z]
|
|
.RS 4
|
|
Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes\&.
|
|
.RE
|
|
.PP
|
|
inflate, deflate, crc32, compress, uncompres, adler32, zlib
|
|
.RS 4
|
|
Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes\&.
|
|
.RE
|
|
.PP
|
|
krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit
|
|
.RS 4
|
|
Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes\&.
|
|
.RE
|
|
.PP
|
|
pakchois_
|
|
.RS 4
|
|
Namespace used by the pakchois library\&.
|
|
.RE
|
|
.PP
|
|
px_
|
|
.RS 4
|
|
Namespace used by the libproxy library\&.
|
|
.RE
|
|
.SS "Argument validation"
|
|
.PP
|
|
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
|
|
\fIundefined behaviour\fR; it is likely that neon will segfault under these conditions\&.
|
|
.SS "URI paths, WebDAV metadata"
|
|
.PP
|
|
The path strings passed to any function must be
|
|
\fIURI\-encoded\fR
|
|
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\&.
|
|
.SS "User interaction"
|
|
.PP
|
|
As a pure library interface, neon will never produce output on
|
|
\fBstdout\fR
|
|
or
|
|
\fBstderr\fR; all user interaction is the responsibilty of the application\&.
|
|
.SS "Memory handling"
|
|
.PP
|
|
neon does not attempt to cope gracefully with an out\-of\-memory situation; instead, by default, the
|
|
\fBabort\fR
|
|
function is called to immediately terminate the process\&. An application may register a custom function which will be called before
|
|
\fBabort\fR
|
|
in such a situation; see
|
|
ne_oom_callback\&.
|
|
.SS "Callbacks and userdata"
|
|
.PP
|
|
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
|
|
\fBvoid *\fR, allowing any pointer to be used\&.
|
|
.SS "Large File Support"
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
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\&.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
ne_session_create(3),
|
|
ne_oom_callback
|
|
.SH "AUTHOR"
|
|
.PP
|
|
\fBJoe Orton\fR <\&neon@lists.manyfish.co.uk\&>
|
|
.RS 4
|
|
Author.
|
|
.RE
|
|
.SH "COPYRIGHT"
|
|
.br
|