base
This commit is contained in:
biosvos
@@ -0,0 +1,257 @@
|
||||
'\" 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
|
||||
Reference in New Issue
Block a user