Debian Codegraph @

deps/libneon/doc/man/neon.3

raw
1 '\" t
2 .\" Title: neon
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NEON" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 neon \- HTTP and WebDAV client library
32 .SH "DESCRIPTION"
33 .PP
34 neon is an HTTP and WebDAV client library\&. The major abstractions exposed are the HTTP
35 \fIsession\fR, created by
36 ne_session_create; and the HTTP
37 \fIrequest\fR, created by
38 ne_request_create\&. HTTP authentication is handled transparently for server and proxy servers, see
39 ne_set_server_auth; complete SSL/TLS support is also included, see
40 ne_ssl_set_verify\&.
41 .SH "CONVENTIONS"
42 .PP
43 Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below\&.
44 .SS "Thread\-safeness and global initialization"
45 .PP
46 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
47 \fBgetaddrinfo\fR
48 interface, which neon supports; some others implement
49 \fBgethostbyname\fR
50 using thread\-local storage\&.
51 .PP
52 To allow thread\-safe use of SSL in the OpenSSL and GnuTLS libraries neon must be configured using the
53 \-\-enable\-threadsafe\-ssl; if this is done, locking callbacks will be registered by
54 ne_sock_init; note that care must be exercised if neon is used in conjunction with another library which uses OpenSSL or GnuTLS\&.
55 .PP
56 Some platforms and libraries used by neon require global initialization before use; notably:
57 .sp
58 .RS 4
59 .ie n \{\
60 \h'-04'\(bu\h'+03'\c
61 .\}
62 .el \{\
63 .sp -1
64 .IP \(bu 2.3
65 .\}
66 The
67 SIGPIPE
68 signal disposition must be set to
69 \fIignored\fR
70 or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer\&.
71 .RE
72 .sp
73 .RS 4
74 .ie n \{\
75 \h'-04'\(bu\h'+03'\c
76 .\}
77 .el \{\
78 .sp -1
79 .IP \(bu 2.3
80 .\}
81 OpenSSL and GnuTLS require global initialization to load shared lookup tables\&.
82 .RE
83 .sp
84 .RS 4
85 .ie n \{\
86 \h'-04'\(bu\h'+03'\c
87 .\}
88 .el \{\
89 .sp -1
90 .IP \(bu 2.3
91 .\}
92 The Win32 socket library requires initialization before use\&.
93 .RE
94 .sp
95 The
96 ne_sock_init
97 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
98 ne_sock_init
99 (and
100 ne_sock_exit); neon neither checks whether these functions are called nor calls them itself\&.
101 .PP
102 For some applications and configurations it may be necessary to call
103 ne_i18n_init
104 to initialize the support for internationalization in neon\&.
105 .SS "Asynchronous signal safety"
106 .PP
107 No function in neon is defined to be
108 \(lqasync\-signal safe\(rq
109 \- 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\&.
110 .SS "Functions using global state"
111 .PP
112 Any function in neon may modify the
113 errno
114 global variable as a side\-effect\&. Except where explicitly documented, the value of
115 errno
116 is unspecified after any neon function call\&.
117 .PP
118 Other than in the use of
119 errno, the only functions which use or modify process\-global state in neon are as follows:
120 .sp
121 .RS 4
122 .ie n \{\
123 \h'-04'\(bu\h'+03'\c
124 .\}
125 .el \{\
126 .sp -1
127 .IP \(bu 2.3
128 .\}
129 ne_sock_init,
130 ne_i18n_init, and
131 ne_sock_exit, as described above
132 .RE
133 .sp
134 .RS 4
135 .ie n \{\
136 \h'-04'\(bu\h'+03'\c
137 .\}
138 .el \{\
139 .sp -1
140 .IP \(bu 2.3
141 .\}
142 \fBne_debug_init\fR
143 and
144 \fBne_debug\fR, if enabled at compile time; for debugging output
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04'\(bu\h'+03'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP \(bu 2.3
154 .\}
155 ne_oom_callback
156 for installing a process\-global callback to be invoked on
157 \fBmalloc\fR
158 failure
159 .RE
160 .SS "Namespaces"
161 .PP
162 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
163 \fInamespace prefix\fR\&. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions\&.
164 .PP
165 The neon library reserves the use of the namespace prefixes
166 ne_
167 and
168 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\&.
169 .PP
170 SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_
171 .RS 4
172 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\&.
173 .RE
174 .PP
175 gnutls_, gcry_, gpg_
176 .RS 4
177 Namespaces used by the GnuTLS library (and dependencies thereof)
178 .RE
179 .PP
180 XML_, Xml[A\-Z]
181 .RS 4
182 Namespaces used by the expat library\&.
183 .RE
184 .PP
185 xml[A\-Z], html[A\-Z], docb[A\-Z]
186 .RS 4
187 Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes\&.
188 .RE
189 .PP
190 inflate, deflate, crc32, compress, uncompres, adler32, zlib
191 .RS 4
192 Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes\&.
193 .RE
194 .PP
195 krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit
196 .RS 4
197 Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes\&.
198 .RE
199 .PP
200 pakchois_
201 .RS 4
202 Namespace used by the pakchois library\&.
203 .RE
204 .PP
205 px_
206 .RS 4
207 Namespace used by the libproxy library\&.
208 .RE
209 .SS "Argument validation"
210 .PP
211 neon does not attempt to validate that the parameters passed to functions conform to the API (for instance, checking that pointer arguments are not
212 NULL)\&. Any use of the neon API which is not documented to produce a certain behaviour results is said to produce
213 \fIundefined behaviour\fR; it is likely that neon will segfault under these conditions\&.
214 .SS "URI paths, WebDAV metadata"
215 .PP
216 The path strings passed to any function must be
217 \fIURI\-encoded\fR
218 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\&.
219 .SS "User interaction"
220 .PP
221 As a pure library interface, neon will never produce output on
222 \fBstdout\fR
223 or
224 \fBstderr\fR; all user interaction is the responsibilty of the application\&.
225 .SS "Memory handling"
226 .PP
227 neon does not attempt to cope gracefully with an out\-of\-memory situation; instead, by default, the
228 \fBabort\fR
229 function is called to immediately terminate the process\&. An application may register a custom function which will be called before
230 \fBabort\fR
231 in such a situation; see
232 ne_oom_callback\&.
233 .SS "Callbacks and userdata"
234 .PP
235 Whenever a callback is registered, a
236 userdata
237 pointer is also used to allow the application to associate a context with the callback\&. The userdata is of type
238 \fBvoid *\fR, allowing any pointer to be used\&.
239 .SS "Large File Support"
240 .PP
241 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
242 off_t
243 type, where LFS support is available\&.
244 .PP
245 Some interfaces use the
246 ne_off_t
247 type, which is defined to be either
248 off_t
249 or
250 off64_t
251 according to whether LFS support is detected at build time\&. neon does not use or require the
252 \-D_FILE_OFFSET_BITS=64
253 macro definition\&.
254 .SH "SEE ALSO"
255 .PP
256 ne_session_create(3),
257 ne_oom_callback
258 .SH "AUTHOR"
259 .PP
260 \fBJoe Orton\fR <\&[email protected]\&>
261 .RS 4
262 Author.
263 .RE
264 .SH "COPYRIGHT"
265 .br