diff options
author | Christian Grothoff <christian@grothoff.org> | 2008-03-30 04:36:05 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2008-03-30 04:36:05 +0000 |
commit | a69c23c79d5385a1c5c6da1587db1c8bcc6ba975 (patch) | |
tree | 2e442244150280b6c11910ce959286b0796b040c | |
parent | a7ea20473a18f5a88028c7245e8e4eaad5982a5a (diff) | |
download | libmicrohttpd-a69c23c79d5385a1c5c6da1587db1c8bcc6ba975.tar.gz libmicrohttpd-a69c23c79d5385a1c5c6da1587db1c8bcc6ba975.zip |
updating docs
-rw-r--r-- | doc/Makefile.am | 6 | ||||
-rw-r--r-- | doc/lgpl.texi | 561 | ||||
-rw-r--r-- | doc/microhttpd.texi | 505 |
3 files changed, 773 insertions, 299 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index b0e78e11..2d8f5578 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am | |||
@@ -1,7 +1,7 @@ | |||
1 | man_MANS = libmicrohttpd.3 | 1 | man_MANS = libmicrohttpd.3 |
2 | EXTRA_DIST = $(man_MANS) | 2 | EXTRA_DIST = $(man_MANS) |
3 | 3 | ||
4 | #DISTCLEANFILES = microhttpd.cps | 4 | DISTCLEANFILES = microhttpd.cps |
5 | #info_TEXINFOS = microhttpd.texi | 5 | info_TEXINFOS = microhttpd.texi |
6 | #microhttpd_TEXINFOS = gpl.texi | 6 | microhttpd_TEXINFOS = lgpl.texi |
7 | 7 | ||
diff --git a/doc/lgpl.texi b/doc/lgpl.texi new file mode 100644 index 00000000..260c0ce0 --- /dev/null +++ b/doc/lgpl.texi | |||
@@ -0,0 +1,561 @@ | |||
1 | @c The GNU Lesser General Public License. | ||
2 | @center Version 2.1, February 1999 | ||
3 | |||
4 | @c This file is intended to be included within another document, | ||
5 | @c hence no sectioning command or @node. | ||
6 | |||
7 | @display | ||
8 | Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc. | ||
9 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA | ||
10 | |||
11 | Everyone is permitted to copy and distribute verbatim copies | ||
12 | of this license document, but changing it is not allowed. | ||
13 | |||
14 | [This is the first released version of the Lesser GPL. It also counts | ||
15 | as the successor of the GNU Library Public License, version 2, hence the | ||
16 | version number 2.1.] | ||
17 | @end display | ||
18 | |||
19 | @subheading Preamble | ||
20 | |||
21 | The licenses for most software are designed to take away your | ||
22 | freedom to share and change it. By contrast, the GNU General Public | ||
23 | Licenses are intended to guarantee your freedom to share and change | ||
24 | free software---to make sure the software is free for all its users. | ||
25 | |||
26 | This license, the Lesser General Public License, applies to some | ||
27 | specially designated software---typically libraries---of the Free | ||
28 | Software Foundation and other authors who decide to use it. You can use | ||
29 | it too, but we suggest you first think carefully about whether this | ||
30 | license or the ordinary General Public License is the better strategy to | ||
31 | use in any particular case, based on the explanations below. | ||
32 | |||
33 | When we speak of free software, we are referring to freedom of use, | ||
34 | not price. Our General Public Licenses are designed to make sure that | ||
35 | you have the freedom to distribute copies of free software (and charge | ||
36 | for this service if you wish); that you receive source code or can get | ||
37 | it if you want it; that you can change the software and use pieces of it | ||
38 | in new free programs; and that you are informed that you can do these | ||
39 | things. | ||
40 | |||
41 | To protect your rights, we need to make restrictions that forbid | ||
42 | distributors to deny you these rights or to ask you to surrender these | ||
43 | rights. These restrictions translate to certain responsibilities for | ||
44 | you if you distribute copies of the library or if you modify it. | ||
45 | |||
46 | For example, if you distribute copies of the library, whether gratis | ||
47 | or for a fee, you must give the recipients all the rights that we gave | ||
48 | you. You must make sure that they, too, receive or can get the source | ||
49 | code. If you link other code with the library, you must provide | ||
50 | complete object files to the recipients, so that they can relink them | ||
51 | with the library after making changes to the library and recompiling | ||
52 | it. And you must show them these terms so they know their rights. | ||
53 | |||
54 | We protect your rights with a two-step method: (1) we copyright the | ||
55 | library, and (2) we offer you this license, which gives you legal | ||
56 | permission to copy, distribute and/or modify the library. | ||
57 | |||
58 | To protect each distributor, we want to make it very clear that | ||
59 | there is no warranty for the free library. Also, if the library is | ||
60 | modified by someone else and passed on, the recipients should know | ||
61 | that what they have is not the original version, so that the original | ||
62 | author's reputation will not be affected by problems that might be | ||
63 | introduced by others. | ||
64 | |||
65 | Finally, software patents pose a constant threat to the existence of | ||
66 | any free program. We wish to make sure that a company cannot | ||
67 | effectively restrict the users of a free program by obtaining a | ||
68 | restrictive license from a patent holder. Therefore, we insist that | ||
69 | any patent license obtained for a version of the library must be | ||
70 | consistent with the full freedom of use specified in this license. | ||
71 | |||
72 | Most GNU software, including some libraries, is covered by the | ||
73 | ordinary GNU General Public License. This license, the GNU Lesser | ||
74 | General Public License, applies to certain designated libraries, and | ||
75 | is quite different from the ordinary General Public License. We use | ||
76 | this license for certain libraries in order to permit linking those | ||
77 | libraries into non-free programs. | ||
78 | |||
79 | When a program is linked with a library, whether statically or using | ||
80 | a shared library, the combination of the two is legally speaking a | ||
81 | combined work, a derivative of the original library. The ordinary | ||
82 | General Public License therefore permits such linking only if the | ||
83 | entire combination fits its criteria of freedom. The Lesser General | ||
84 | Public License permits more lax criteria for linking other code with | ||
85 | the library. | ||
86 | |||
87 | We call this license the @dfn{Lesser} General Public License because it | ||
88 | does @emph{Less} to protect the user's freedom than the ordinary General | ||
89 | Public License. It also provides other free software developers Less | ||
90 | of an advantage over competing non-free programs. These disadvantages | ||
91 | are the reason we use the ordinary General Public License for many | ||
92 | libraries. However, the Lesser license provides advantages in certain | ||
93 | special circumstances. | ||
94 | |||
95 | For example, on rare occasions, there may be a special need to | ||
96 | encourage the widest possible use of a certain library, so that it becomes | ||
97 | a de-facto standard. To achieve this, non-free programs must be | ||
98 | allowed to use the library. A more frequent case is that a free | ||
99 | library does the same job as widely used non-free libraries. In this | ||
100 | case, there is little to gain by limiting the free library to free | ||
101 | software only, so we use the Lesser General Public License. | ||
102 | |||
103 | In other cases, permission to use a particular library in non-free | ||
104 | programs enables a greater number of people to use a large body of | ||
105 | free software. For example, permission to use the GNU C Library in | ||
106 | non-free programs enables many more people to use the whole GNU | ||
107 | operating system, as well as its variant, the GNU/Linux operating | ||
108 | system. | ||
109 | |||
110 | Although the Lesser General Public License is Less protective of the | ||
111 | users' freedom, it does ensure that the user of a program that is | ||
112 | linked with the Library has the freedom and the wherewithal to run | ||
113 | that program using a modified version of the Library. | ||
114 | |||
115 | The precise terms and conditions for copying, distribution and | ||
116 | modification follow. Pay close attention to the difference between a | ||
117 | ``work based on the library'' and a ``work that uses the library''. The | ||
118 | former contains code derived from the library, whereas the latter must | ||
119 | be combined with the library in order to run. | ||
120 | |||
121 | @subheading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | ||
122 | |||
123 | @enumerate 0 | ||
124 | @item | ||
125 | This License Agreement applies to any software library or other program | ||
126 | which contains a notice placed by the copyright holder or other | ||
127 | authorized party saying it may be distributed under the terms of this | ||
128 | Lesser General Public License (also called ``this License''). Each | ||
129 | licensee is addressed as ``you''. | ||
130 | |||
131 | A ``library'' means a collection of software functions and/or data | ||
132 | prepared so as to be conveniently linked with application programs | ||
133 | (which use some of those functions and data) to form executables. | ||
134 | |||
135 | The ``Library'', below, refers to any such software library or work | ||
136 | which has been distributed under these terms. A ``work based on the | ||
137 | Library'' means either the Library or any derivative work under | ||
138 | copyright law: that is to say, a work containing the Library or a | ||
139 | portion of it, either verbatim or with modifications and/or translated | ||
140 | straightforwardly into another language. (Hereinafter, translation is | ||
141 | included without limitation in the term ``modification''.) | ||
142 | |||
143 | ``Source code'' for a work means the preferred form of the work for | ||
144 | making modifications to it. For a library, complete source code means | ||
145 | all the source code for all modules it contains, plus any associated | ||
146 | interface definition files, plus the scripts used to control compilation | ||
147 | and installation of the library. | ||
148 | |||
149 | Activities other than copying, distribution and modification are not | ||
150 | covered by this License; they are outside its scope. The act of | ||
151 | running a program using the Library is not restricted, and output from | ||
152 | such a program is covered only if its contents constitute a work based | ||
153 | on the Library (independent of the use of the Library in a tool for | ||
154 | writing it). Whether that is true depends on what the Library does | ||
155 | and what the program that uses the Library does. | ||
156 | |||
157 | @item | ||
158 | You may copy and distribute verbatim copies of the Library's | ||
159 | complete source code as you receive it, in any medium, provided that | ||
160 | you conspicuously and appropriately publish on each copy an | ||
161 | appropriate copyright notice and disclaimer of warranty; keep intact | ||
162 | all the notices that refer to this License and to the absence of any | ||
163 | warranty; and distribute a copy of this License along with the | ||
164 | Library. | ||
165 | |||
166 | You may charge a fee for the physical act of transferring a copy, | ||
167 | and you may at your option offer warranty protection in exchange for a | ||
168 | fee. | ||
169 | |||
170 | @item | ||
171 | You may modify your copy or copies of the Library or any portion | ||
172 | of it, thus forming a work based on the Library, and copy and | ||
173 | distribute such modifications or work under the terms of Section 1 | ||
174 | above, provided that you also meet all of these conditions: | ||
175 | |||
176 | @enumerate a | ||
177 | @item | ||
178 | The modified work must itself be a software library. | ||
179 | |||
180 | @item | ||
181 | You must cause the files modified to carry prominent notices | ||
182 | stating that you changed the files and the date of any change. | ||
183 | |||
184 | @item | ||
185 | You must cause the whole of the work to be licensed at no | ||
186 | charge to all third parties under the terms of this License. | ||
187 | |||
188 | @item | ||
189 | If a facility in the modified Library refers to a function or a | ||
190 | table of data to be supplied by an application program that uses | ||
191 | the facility, other than as an argument passed when the facility | ||
192 | is invoked, then you must make a good faith effort to ensure that, | ||
193 | in the event an application does not supply such function or | ||
194 | table, the facility still operates, and performs whatever part of | ||
195 | its purpose remains meaningful. | ||
196 | |||
197 | (For example, a function in a library to compute square roots has | ||
198 | a purpose that is entirely well-defined independent of the | ||
199 | application. Therefore, Subsection 2d requires that any | ||
200 | application-supplied function or table used by this function must | ||
201 | be optional: if the application does not supply it, the square | ||
202 | root function must still compute square roots.) | ||
203 | @end enumerate | ||
204 | |||
205 | These requirements apply to the modified work as a whole. If | ||
206 | identifiable sections of that work are not derived from the Library, | ||
207 | and can be reasonably considered independent and separate works in | ||
208 | themselves, then this License, and its terms, do not apply to those | ||
209 | sections when you distribute them as separate works. But when you | ||
210 | distribute the same sections as part of a whole which is a work based | ||
211 | on the Library, the distribution of the whole must be on the terms of | ||
212 | this License, whose permissions for other licensees extend to the | ||
213 | entire whole, and thus to each and every part regardless of who wrote | ||
214 | it. | ||
215 | |||
216 | Thus, it is not the intent of this section to claim rights or contest | ||
217 | your rights to work written entirely by you; rather, the intent is to | ||
218 | exercise the right to control the distribution of derivative or | ||
219 | collective works based on the Library. | ||
220 | |||
221 | In addition, mere aggregation of another work not based on the Library | ||
222 | with the Library (or with a work based on the Library) on a volume of | ||
223 | a storage or distribution medium does not bring the other work under | ||
224 | the scope of this License. | ||
225 | |||
226 | @item | ||
227 | You may opt to apply the terms of the ordinary GNU General Public | ||
228 | License instead of this License to a given copy of the Library. To do | ||
229 | this, you must alter all the notices that refer to this License, so | ||
230 | that they refer to the ordinary GNU General Public License, version 2, | ||
231 | instead of to this License. (If a newer version than version 2 of the | ||
232 | ordinary GNU General Public License has appeared, then you can specify | ||
233 | that version instead if you wish.) Do not make any other change in | ||
234 | these notices. | ||
235 | |||
236 | Once this change is made in a given copy, it is irreversible for | ||
237 | that copy, so the ordinary GNU General Public License applies to all | ||
238 | subsequent copies and derivative works made from that copy. | ||
239 | |||
240 | This option is useful when you wish to copy part of the code of | ||
241 | the Library into a program that is not a library. | ||
242 | |||
243 | @item | ||
244 | You may copy and distribute the Library (or a portion or | ||
245 | derivative of it, under Section 2) in object code or executable form | ||
246 | under the terms of Sections 1 and 2 above provided that you accompany | ||
247 | it with the complete corresponding machine-readable source code, which | ||
248 | must be distributed under the terms of Sections 1 and 2 above on a | ||
249 | medium customarily used for software interchange. | ||
250 | |||
251 | If distribution of object code is made by offering access to copy | ||
252 | from a designated place, then offering equivalent access to copy the | ||
253 | source code from the same place satisfies the requirement to | ||
254 | distribute the source code, even though third parties are not | ||
255 | compelled to copy the source along with the object code. | ||
256 | |||
257 | @item | ||
258 | A program that contains no derivative of any portion of the | ||
259 | Library, but is designed to work with the Library by being compiled or | ||
260 | linked with it, is called a ``work that uses the Library''. Such a | ||
261 | work, in isolation, is not a derivative work of the Library, and | ||
262 | therefore falls outside the scope of this License. | ||
263 | |||
264 | However, linking a ``work that uses the Library'' with the Library | ||
265 | creates an executable that is a derivative of the Library (because it | ||
266 | contains portions of the Library), rather than a ``work that uses the | ||
267 | library''. The executable is therefore covered by this License. | ||
268 | Section 6 states terms for distribution of such executables. | ||
269 | |||
270 | When a ``work that uses the Library'' uses material from a header file | ||
271 | that is part of the Library, the object code for the work may be a | ||
272 | derivative work of the Library even though the source code is not. | ||
273 | Whether this is true is especially significant if the work can be | ||
274 | linked without the Library, or if the work is itself a library. The | ||
275 | threshold for this to be true is not precisely defined by law. | ||
276 | |||
277 | If such an object file uses only numerical parameters, data | ||
278 | structure layouts and accessors, and small macros and small inline | ||
279 | functions (ten lines or less in length), then the use of the object | ||
280 | file is unrestricted, regardless of whether it is legally a derivative | ||
281 | work. (Executables containing this object code plus portions of the | ||
282 | Library will still fall under Section 6.) | ||
283 | |||
284 | Otherwise, if the work is a derivative of the Library, you may | ||
285 | distribute the object code for the work under the terms of Section 6. | ||
286 | Any executables containing that work also fall under Section 6, | ||
287 | whether or not they are linked directly with the Library itself. | ||
288 | |||
289 | @item | ||
290 | As an exception to the Sections above, you may also combine or | ||
291 | link a ``work that uses the Library'' with the Library to produce a | ||
292 | work containing portions of the Library, and distribute that work | ||
293 | under terms of your choice, provided that the terms permit | ||
294 | modification of the work for the customer's own use and reverse | ||
295 | engineering for debugging such modifications. | ||
296 | |||
297 | You must give prominent notice with each copy of the work that the | ||
298 | Library is used in it and that the Library and its use are covered by | ||
299 | this License. You must supply a copy of this License. If the work | ||
300 | during execution displays copyright notices, you must include the | ||
301 | copyright notice for the Library among them, as well as a reference | ||
302 | directing the user to the copy of this License. Also, you must do one | ||
303 | of these things: | ||
304 | |||
305 | @enumerate a | ||
306 | @item | ||
307 | Accompany the work with the complete corresponding | ||
308 | machine-readable source code for the Library including whatever | ||
309 | changes were used in the work (which must be distributed under | ||
310 | Sections 1 and 2 above); and, if the work is an executable linked | ||
311 | with the Library, with the complete machine-readable ``work that | ||
312 | uses the Library'', as object code and/or source code, so that the | ||
313 | user can modify the Library and then relink to produce a modified | ||
314 | executable containing the modified Library. (It is understood | ||
315 | that the user who changes the contents of definitions files in the | ||
316 | Library will not necessarily be able to recompile the application | ||
317 | to use the modified definitions.) | ||
318 | |||
319 | @item | ||
320 | Use a suitable shared library mechanism for linking with the Library. A | ||
321 | suitable mechanism is one that (1) uses at run time a copy of the | ||
322 | library already present on the user's computer system, rather than | ||
323 | copying library functions into the executable, and (2) will operate | ||
324 | properly with a modified version of the library, if the user installs | ||
325 | one, as long as the modified version is interface-compatible with the | ||
326 | version that the work was made with. | ||
327 | |||
328 | @item | ||
329 | Accompany the work with a written offer, valid for at | ||
330 | least three years, to give the same user the materials | ||
331 | specified in Subsection 6a, above, for a charge no more | ||
332 | than the cost of performing this distribution. | ||
333 | |||
334 | @item | ||
335 | If distribution of the work is made by offering access to copy | ||
336 | from a designated place, offer equivalent access to copy the above | ||
337 | specified materials from the same place. | ||
338 | |||
339 | @item | ||
340 | Verify that the user has already received a copy of these | ||
341 | materials or that you have already sent this user a copy. | ||
342 | @end enumerate | ||
343 | |||
344 | For an executable, the required form of the ``work that uses the | ||
345 | Library'' must include any data and utility programs needed for | ||
346 | reproducing the executable from it. However, as a special exception, | ||
347 | the materials to be distributed need not include anything that is | ||
348 | normally distributed (in either source or binary form) with the major | ||
349 | components (compiler, kernel, and so on) of the operating system on | ||
350 | which the executable runs, unless that component itself accompanies the | ||
351 | executable. | ||
352 | |||
353 | It may happen that this requirement contradicts the license | ||
354 | restrictions of other proprietary libraries that do not normally | ||
355 | accompany the operating system. Such a contradiction means you cannot | ||
356 | use both them and the Library together in an executable that you | ||
357 | distribute. | ||
358 | |||
359 | @item | ||
360 | You may place library facilities that are a work based on the | ||
361 | Library side-by-side in a single library together with other library | ||
362 | facilities not covered by this License, and distribute such a combined | ||
363 | library, provided that the separate distribution of the work based on | ||
364 | the Library and of the other library facilities is otherwise | ||
365 | permitted, and provided that you do these two things: | ||
366 | |||
367 | @enumerate a | ||
368 | @item | ||
369 | Accompany the combined library with a copy of the same work | ||
370 | based on the Library, uncombined with any other library | ||
371 | facilities. This must be distributed under the terms of the | ||
372 | Sections above. | ||
373 | |||
374 | @item | ||
375 | Give prominent notice with the combined library of the fact | ||
376 | that part of it is a work based on the Library, and explaining | ||
377 | where to find the accompanying uncombined form of the same work. | ||
378 | @end enumerate | ||
379 | |||
380 | @item | ||
381 | You may not copy, modify, sublicense, link with, or distribute | ||
382 | the Library except as expressly provided under this License. Any | ||
383 | attempt otherwise to copy, modify, sublicense, link with, or | ||
384 | distribute the Library is void, and will automatically terminate your | ||
385 | rights under this License. However, parties who have received copies, | ||
386 | or rights, from you under this License will not have their licenses | ||
387 | terminated so long as such parties remain in full compliance. | ||
388 | |||
389 | @item | ||
390 | You are not required to accept this License, since you have not | ||
391 | signed it. However, nothing else grants you permission to modify or | ||
392 | distribute the Library or its derivative works. These actions are | ||
393 | prohibited by law if you do not accept this License. Therefore, by | ||
394 | modifying or distributing the Library (or any work based on the | ||
395 | Library), you indicate your acceptance of this License to do so, and | ||
396 | all its terms and conditions for copying, distributing or modifying | ||
397 | the Library or works based on it. | ||
398 | |||
399 | @item | ||
400 | Each time you redistribute the Library (or any work based on the | ||
401 | Library), the recipient automatically receives a license from the | ||
402 | original licensor to copy, distribute, link with or modify the Library | ||
403 | subject to these terms and conditions. You may not impose any further | ||
404 | restrictions on the recipients' exercise of the rights granted herein. | ||
405 | You are not responsible for enforcing compliance by third parties with | ||
406 | this License. | ||
407 | |||
408 | @item | ||
409 | If, as a consequence of a court judgment or allegation of patent | ||
410 | infringement or for any other reason (not limited to patent issues), | ||
411 | conditions are imposed on you (whether by court order, agreement or | ||
412 | otherwise) that contradict the conditions of this License, they do not | ||
413 | excuse you from the conditions of this License. If you cannot | ||
414 | distribute so as to satisfy simultaneously your obligations under this | ||
415 | License and any other pertinent obligations, then as a consequence you | ||
416 | may not distribute the Library at all. For example, if a patent | ||
417 | license would not permit royalty-free redistribution of the Library by | ||
418 | all those who receive copies directly or indirectly through you, then | ||
419 | the only way you could satisfy both it and this License would be to | ||
420 | refrain entirely from distribution of the Library. | ||
421 | |||
422 | If any portion of this section is held invalid or unenforceable under any | ||
423 | particular circumstance, the balance of the section is intended to apply, | ||
424 | and the section as a whole is intended to apply in other circumstances. | ||
425 | |||
426 | It is not the purpose of this section to induce you to infringe any | ||
427 | patents or other property right claims or to contest validity of any | ||
428 | such claims; this section has the sole purpose of protecting the | ||
429 | integrity of the free software distribution system which is | ||
430 | implemented by public license practices. Many people have made | ||
431 | generous contributions to the wide range of software distributed | ||
432 | through that system in reliance on consistent application of that | ||
433 | system; it is up to the author/donor to decide if he or she is willing | ||
434 | to distribute software through any other system and a licensee cannot | ||
435 | impose that choice. | ||
436 | |||
437 | This section is intended to make thoroughly clear what is believed to | ||
438 | be a consequence of the rest of this License. | ||
439 | |||
440 | @item | ||
441 | If the distribution and/or use of the Library is restricted in | ||
442 | certain countries either by patents or by copyrighted interfaces, the | ||
443 | original copyright holder who places the Library under this License may add | ||
444 | an explicit geographical distribution limitation excluding those countries, | ||
445 | so that distribution is permitted only in or among countries not thus | ||
446 | excluded. In such case, this License incorporates the limitation as if | ||
447 | written in the body of this License. | ||
448 | |||
449 | @item | ||
450 | The Free Software Foundation may publish revised and/or new | ||
451 | versions of the Lesser General Public License from time to time. | ||
452 | Such new versions will be similar in spirit to the present version, | ||
453 | but may differ in detail to address new problems or concerns. | ||
454 | |||
455 | Each version is given a distinguishing version number. If the Library | ||
456 | specifies a version number of this License which applies to it and | ||
457 | ``any later version'', you have the option of following the terms and | ||
458 | conditions either of that version or of any later version published by | ||
459 | the Free Software Foundation. If the Library does not specify a | ||
460 | license version number, you may choose any version ever published by | ||
461 | the Free Software Foundation. | ||
462 | |||
463 | @item | ||
464 | If you wish to incorporate parts of the Library into other free | ||
465 | programs whose distribution conditions are incompatible with these, | ||
466 | write to the author to ask for permission. For software which is | ||
467 | copyrighted by the Free Software Foundation, write to the Free | ||
468 | Software Foundation; we sometimes make exceptions for this. Our | ||
469 | decision will be guided by the two goals of preserving the free status | ||
470 | of all derivatives of our free software and of promoting the sharing | ||
471 | and reuse of software generally. | ||
472 | |||
473 | @iftex | ||
474 | @heading NO WARRANTY | ||
475 | @end iftex | ||
476 | @ifinfo | ||
477 | @center NO WARRANTY | ||
478 | |||
479 | @end ifinfo | ||
480 | |||
481 | @item | ||
482 | BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO | ||
483 | WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. | ||
484 | EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR | ||
485 | OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY | ||
486 | KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE | ||
487 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
488 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE | ||
489 | LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME | ||
490 | THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. | ||
491 | |||
492 | @item | ||
493 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN | ||
494 | WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY | ||
495 | AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU | ||
496 | FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR | ||
497 | CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE | ||
498 | LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING | ||
499 | RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A | ||
500 | FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF | ||
501 | SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH | ||
502 | DAMAGES. | ||
503 | @end enumerate | ||
504 | |||
505 | @iftex | ||
506 | @heading END OF TERMS AND CONDITIONS | ||
507 | @end iftex | ||
508 | @ifinfo | ||
509 | @center END OF TERMS AND CONDITIONS | ||
510 | |||
511 | @end ifinfo | ||
512 | |||
513 | @page | ||
514 | @subheading How to Apply These Terms to Your New Libraries | ||
515 | |||
516 | If you develop a new library, and you want it to be of the greatest | ||
517 | possible use to the public, we recommend making it free software that | ||
518 | everyone can redistribute and change. You can do so by permitting | ||
519 | redistribution under these terms (or, alternatively, under the terms of the | ||
520 | ordinary General Public License). | ||
521 | |||
522 | To apply these terms, attach the following notices to the library. It is | ||
523 | safest to attach them to the start of each source file to most effectively | ||
524 | convey the exclusion of warranty; and each file should have at least the | ||
525 | ``copyright'' line and a pointer to where the full notice is found. | ||
526 | |||
527 | @smallexample | ||
528 | @var{one line to give the library's name and an idea of what it does.} | ||
529 | Copyright (C) @var{year} @var{name of author} | ||
530 | |||
531 | This library is free software; you can redistribute it and/or modify it | ||
532 | under the terms of the GNU Lesser General Public License as published by | ||
533 | the Free Software Foundation; either version 2.1 of the License, or (at | ||
534 | your option) any later version. | ||
535 | |||
536 | This library is distributed in the hope that it will be useful, but | ||
537 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
538 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
539 | Lesser General Public License for more details. | ||
540 | |||
541 | You should have received a copy of the GNU Lesser General Public | ||
542 | License along with this library; if not, write to the Free Software | ||
543 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, | ||
544 | USA. | ||
545 | @end smallexample | ||
546 | |||
547 | Also add information on how to contact you by electronic and paper mail. | ||
548 | |||
549 | You should also get your employer (if you work as a programmer) or your | ||
550 | school, if any, to sign a ``copyright disclaimer'' for the library, if | ||
551 | necessary. Here is a sample; alter the names: | ||
552 | |||
553 | @smallexample | ||
554 | Yoyodyne, Inc., hereby disclaims all copyright interest in the library | ||
555 | `Frob' (a library for tweaking knobs) written by James Random Hacker. | ||
556 | |||
557 | @var{signature of Ty Coon}, 1 April 1990 | ||
558 | Ty Coon, President of Vice | ||
559 | @end smallexample | ||
560 | |||
561 | That's all there is to it! | ||
diff --git a/doc/microhttpd.texi b/doc/microhttpd.texi index 8d061179..4e0ad512 100644 --- a/doc/microhttpd.texi +++ b/doc/microhttpd.texi | |||
@@ -1,4 +1,48 @@ | |||
1 | \input texinfo | ||
1 | @setfilename microhttpd.info | 2 | @setfilename microhttpd.info |
3 | @include version.texi | ||
4 | @settitle The libmicrohttpd Reference Manual | ||
5 | @c Unify some of the indices. | ||
6 | @c %**end of header | ||
7 | @copying | ||
8 | This manual documents libmicrohttpd version @value{VERSION}, last | ||
9 | updated @value{UPDATED}. It is built upon the documentation in the | ||
10 | header file @file{microhttpd.h}. | ||
11 | |||
12 | @noindent | ||
13 | |||
14 | Copyright @copyright{} 2007, 2008 Christian Grothoff | ||
15 | |||
16 | @quotation | ||
17 | FIXME: add license terms here! | ||
18 | @end quotation | ||
19 | @end copying | ||
20 | |||
21 | @dircategory GNU Libraries | ||
22 | @direntry | ||
23 | * libmicrohttpd: (microhttpd). Embedded HTTP server library. | ||
24 | @end direntry | ||
25 | |||
26 | @c | ||
27 | @c Titlepage | ||
28 | @c | ||
29 | @setchapternewpage odd | ||
30 | @titlepage | ||
31 | @title The libmicrohttpd Reference Manual | ||
32 | @subtitle Version @value{VERSION} | ||
33 | @subtitle @value{UPDATED} | ||
34 | @author Marco Maggi (@email{marco.maggi-ipsu@@poste.it}) | ||
35 | @author Christian Grothoff (@email{christian@@grothoff.org}) | ||
36 | |||
37 | @page | ||
38 | @vskip 0pt plus 1filll | ||
39 | @insertcopying | ||
40 | @end titlepage | ||
41 | |||
42 | @summarycontents | ||
43 | @contents | ||
44 | @page | ||
45 | |||
2 | 46 | ||
3 | @macro gnu{} | 47 | @macro gnu{} |
4 | @acronym{GNU} | 48 | @acronym{GNU} |
@@ -34,14 +78,18 @@ | |||
34 | 78 | ||
35 | @c ............................................................ | 79 | @c ............................................................ |
36 | 80 | ||
37 | @macro cfunction{NAME} | 81 | @macro cfunction{arg} |
38 | @code{\NAME\()} | 82 | @code{\arg\()} |
39 | @end macro | 83 | @end macro |
40 | 84 | ||
41 | @macro null{} | 85 | @macro mynull{} |
42 | @code{NULL} | 86 | @code{NULL} |
43 | @end macro | 87 | @end macro |
44 | 88 | ||
89 | @macro mhd{} | ||
90 | @acronym{MHD} | ||
91 | @end macro | ||
92 | |||
45 | @c ............................................................ | 93 | @c ............................................................ |
46 | 94 | ||
47 | @macro glibcref{NODE, NODE} | 95 | @macro glibcref{NODE, NODE} |
@@ -52,36 +100,40 @@ | |||
52 | 100 | ||
53 | 101 | ||
54 | @c ------------------------------------------------------------ | 102 | @c ------------------------------------------------------------ |
55 | @node microhttpd | 103 | @ifnottex |
56 | @appendix Libmicrohttpd documentation | 104 | @node Top |
57 | 105 | @top The libmicrohttpd Library | |
58 | 106 | @insertcopying | |
59 | @macro mhd{} | 107 | @end ifnottex |
60 | @acronym{MHD} | ||
61 | @end macro | ||
62 | |||
63 | |||
64 | @noindent | ||
65 | This appendix documents Libmicrohttpd version 0.1.2. It is built upon | ||
66 | the documentation in the header file @file{microhttpd.h}. | ||
67 | 108 | ||
68 | @menu | 109 | @menu |
69 | * microhttpd intro:: Introduction. | 110 | * microhttpd-intro:: Introduction. |
70 | * microhttpd const:: Constants. | 111 | * microhttpd-const:: Constants. |
71 | * microhttpd struct:: Structures type definition. | 112 | * microhttpd-struct:: Structures type definition. |
72 | * microhttpd cb:: Callback functions definition. | 113 | * microhttpd-cb:: Callback functions definition. |
73 | * microhttpd init:: Starting and stopping the server. | 114 | * microhttpd-init:: Starting and stopping the server. |
74 | * microhttpd inspect:: Inspection. | 115 | * microhttpd-inspect:: Implementing external @code{select}. |
75 | * microhttpd requests:: Handling requests. | 116 | * microhttpd-requests:: Handling requests. |
76 | * microhttpd responses:: Building responses to requests. | 117 | * microhttpd-responses:: Building responses to requests. |
77 | * microhttpd post:: Adding a @code{POST} processor. | 118 | * microhttpd-post:: Adding a @code{POST} processor. |
119 | |||
120 | Appendices | ||
121 | |||
122 | * Copying:: The GNU Lesser General Public License says how you | ||
123 | can copy and share some parts of `libmicrohttpd'. | ||
124 | |||
125 | Indices | ||
126 | |||
127 | * Concept Index:: Index of concepts and programs. | ||
128 | * Function and Data Index:: Index of functions, variables and data types. | ||
129 | * Type Index:: Index of data types. | ||
78 | @end menu | 130 | @end menu |
79 | 131 | ||
80 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 132 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
81 | 133 | ||
82 | @c ------------------------------------------------------------ | 134 | @c ------------------------------------------------------------ |
83 | @node microhttpd intro | 135 | @node microhttpd-intro |
84 | @appendixsec Introduction | 136 | @chapter Introduction |
85 | 137 | ||
86 | 138 | ||
87 | @noindent | 139 | @noindent |
@@ -103,11 +155,11 @@ library also understands headers that control connection management | |||
103 | are understood and handled automatically). | 155 | are understood and handled automatically). |
104 | 156 | ||
105 | @mhd{} understands @code{POST} data and is able to decode certain | 157 | @mhd{} understands @code{POST} data and is able to decode certain |
106 | formats (at the moment only @code{application/x-www-form-urlencoded}) if | 158 | formats (at the moment only @code{application/x-www-form-urlencoded} |
107 | the entire data fits into the allowed amount of memory for the | 159 | and @code{multipart/form-data}) using the post processor API. The |
108 | connection. Unsupported encodings and large @code{POST} submissions are | 160 | data stream of a POST is also provided directly to the main |
109 | provided as a stream to the main application (and thus can be processed, | 161 | application, so unsupported encodings could still be processed, just |
110 | just not conveniently by @mhd{}). | 162 | not conveniently by @mhd{}. |
111 | 163 | ||
112 | The header file defines various constants used by the @http{} protocol. | 164 | The header file defines various constants used by the @http{} protocol. |
113 | This does not mean that @mhd{} actually interprets all of these values. | 165 | This does not mean that @mhd{} actually interprets all of these values. |
@@ -118,15 +170,19 @@ define their own extensions of the @http{} standard and use those with | |||
118 | @mhd{}. | 170 | @mhd{}. |
119 | 171 | ||
120 | All functions are guaranteed to be completely reentrant and | 172 | All functions are guaranteed to be completely reentrant and |
121 | thread-safe. | 173 | thread-safe. @mhd{} checks for allocation failures and tries to |
174 | recover gracefully (for example, by closing the connection). | ||
175 | Additionally, clients can specify resource limits on the overall | ||
176 | number of connections, number of connections per IP address and memory | ||
177 | used per connection to avoid resource exhaustion. | ||
122 | 178 | ||
123 | 179 | ||
124 | 180 | ||
125 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 181 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
126 | 182 | ||
127 | @c ------------------------------------------------------------ | 183 | @c ------------------------------------------------------------ |
128 | @node microhttpd const | 184 | @node microhttpd-const |
129 | @appendixsec Constants | 185 | @chapter Constants |
130 | 186 | ||
131 | 187 | ||
132 | @deftp {Enumeration} MHD_FLAG | 188 | @deftp {Enumeration} MHD_FLAG |
@@ -146,10 +202,12 @@ No options selected. | |||
146 | 202 | ||
147 | @item MHD_USE_DEBUG | 203 | @item MHD_USE_DEBUG |
148 | Run in debug mode. If this flag is used, the library should print error | 204 | Run in debug mode. If this flag is used, the library should print error |
149 | messages and warnings to stderr. | 205 | messages and warnings to stderr. Note that @mhd{} also needs to be |
206 | compiled with the configure option @code{--enable-messages} for this | ||
207 | run-time option to have any effect. | ||
150 | 208 | ||
151 | @item MHD_USE_SSL | 209 | @item MHD_USE_SSL |
152 | Run in https mode. | 210 | Run in https mode (this is not yet supported). |
153 | 211 | ||
154 | @item MHD_USE_THREAD_PER_CONNECTION | 212 | @item MHD_USE_THREAD_PER_CONNECTION |
155 | Run using one thread per connection. | 213 | Run using one thread per connection. |
@@ -204,7 +262,21 @@ notifications. | |||
204 | This option should be followed by @strong{TWO} pointers. First a | 262 | This option should be followed by @strong{TWO} pointers. First a |
205 | pointer to a function of type @cfunction{MHD_RequestCompletedCallback} | 263 | pointer to a function of type @cfunction{MHD_RequestCompletedCallback} |
206 | and second a pointer to a closure to pass to the request completed | 264 | and second a pointer to a closure to pass to the request completed |
207 | callback. The second pointer maybe @null{}. | 265 | callback. The second pointer maybe @mynull{}. |
266 | |||
267 | |||
268 | @item MHD_OPTION_PER_IP_CONNECTION_LIMIT | ||
269 | Limit on the number of (concurrent) connections made to the | ||
270 | server from the same IP address. Can be used to prevent one | ||
271 | IP from taking over all of the allowed connections. If the | ||
272 | same IP tries to establish more than the specified number of | ||
273 | connections, they will be immediately rejected. The option | ||
274 | should be followed by an @code{unsigned int}. The default is | ||
275 | zero, which means no limit on the number of connections | ||
276 | from the same IP address. | ||
277 | |||
278 | |||
279 | |||
208 | @end table | 280 | @end table |
209 | @end deftp | 281 | @end deftp |
210 | 282 | ||
@@ -234,6 +306,10 @@ already been processed). | |||
234 | 306 | ||
235 | @item MHD_GET_ARGUMENT_KIND | 307 | @item MHD_GET_ARGUMENT_KIND |
236 | @code{GET} (@uri{}) arguments. | 308 | @code{GET} (@uri{}) arguments. |
309 | |||
310 | @item MHD_HEADER_KIND | ||
311 | @http{} footer (only for http 1.1 chunked encodings). | ||
312 | |||
237 | @end table | 313 | @end table |
238 | @end deftp | 314 | @end deftp |
239 | 315 | ||
@@ -263,8 +339,8 @@ We had to close the session since @mhd{} was being shut down. | |||
263 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 339 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
264 | 340 | ||
265 | @c ------------------------------------------------------------ | 341 | @c ------------------------------------------------------------ |
266 | @node microhttpd struct | 342 | @node microhttpd-struct |
267 | @appendixsec Structures type definition | 343 | @chapter Structures type definition |
268 | 344 | ||
269 | 345 | ||
270 | @deftp {C Struct} MHD_Daemon | 346 | @deftp {C Struct} MHD_Daemon |
@@ -292,8 +368,8 @@ Handle for @code{POST} processing. | |||
292 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 368 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
293 | 369 | ||
294 | @c ------------------------------------------------------------ | 370 | @c ------------------------------------------------------------ |
295 | @node microhttpd cb | 371 | @node microhttpd-cb |
296 | @appendixsec Callback functions definition | 372 | @chapter Callback functions definition |
297 | 373 | ||
298 | 374 | ||
299 | @deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) | 375 | @deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) |
@@ -319,7 +395,7 @@ client. This callback must call @mhd{} functions (example: the | |||
319 | and return an @http{} status code (i.e. @code{200} for OK, @code{404}, | 395 | and return an @http{} status code (i.e. @code{200} for OK, @code{404}, |
320 | etc.). | 396 | etc.). |
321 | 397 | ||
322 | @ref{microhttpd post}, for details on how to code this callback. | 398 | @ref{microhttpd-post}, for details on how to code this callback. |
323 | 399 | ||
324 | Must return @code{MHD_YES} if the connection was handled successfully, | 400 | Must return @code{MHD_YES} if the connection was handled successfully, |
325 | @code{MHD_NO} if the socket must be closed due to a serious error while | 401 | @code{MHD_NO} if the socket must be closed due to a serious error while |
@@ -360,7 +436,7 @@ callback must update this value to the number of bytes @strong{NOT} | |||
360 | processed; | 436 | processed; |
361 | 437 | ||
362 | @item con_cls | 438 | @item con_cls |
363 | reference to a pointer, initially set to @null{}, that this callback can | 439 | reference to a pointer, initially set to @mynull{}, that this callback can |
364 | set to some address and that will be preserved by @mhd{} for future | 440 | set to some address and that will be preserved by @mhd{} for future |
365 | calls for this request; | 441 | calls for this request; |
366 | 442 | ||
@@ -459,13 +535,13 @@ type of the value; | |||
459 | zero-terminated key for the value; | 535 | zero-terminated key for the value; |
460 | 536 | ||
461 | @item filename | 537 | @item filename |
462 | name of the uploaded file, @null{} if not known; | 538 | name of the uploaded file, @mynull{} if not known; |
463 | 539 | ||
464 | @item content_type | 540 | @item content_type |
465 | mime-type of the data, @null{} if not known; | 541 | mime-type of the data, @mynull{} if not known; |
466 | 542 | ||
467 | @item transfer_encoding | 543 | @item transfer_encoding |
468 | encoding of the data, @null{} if not known; | 544 | encoding of the data, @mynull{} if not known; |
469 | 545 | ||
470 | @item data | 546 | @item data |
471 | pointer to size bytes of data at the specified offset; | 547 | pointer to size bytes of data at the specified offset; |
@@ -485,8 +561,8 @@ iteration. | |||
485 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 561 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
486 | 562 | ||
487 | @c ------------------------------------------------------------ | 563 | @c ------------------------------------------------------------ |
488 | @node microhttpd init | 564 | @node microhttpd-init |
489 | @appendixsec Starting and stopping the server | 565 | @chapter Starting and stopping the server |
490 | 566 | ||
491 | 567 | ||
492 | @deftypefun {struct MHD_Daemon *} MHD_start_daemon (unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...) | 568 | @deftypefun {struct MHD_Daemon *} MHD_start_daemon (unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...) |
@@ -501,7 +577,7 @@ port to bind to; | |||
501 | 577 | ||
502 | @item apc | 578 | @item apc |
503 | callback to call to check which clients will be allowed to connect; you | 579 | callback to call to check which clients will be allowed to connect; you |
504 | can pass @null{} in which case connections from any @acronym{IP} will be | 580 | can pass @mynull{} in which case connections from any @acronym{IP} will be |
505 | accepted; | 581 | accepted; |
506 | 582 | ||
507 | @item apc_cls | 583 | @item apc_cls |
@@ -519,7 +595,7 @@ terminated with @code{MHD_OPTION_END}). It is mandatory to use | |||
519 | @code{MHD_OPTION_END} as last argument, even when there are no | 595 | @code{MHD_OPTION_END} as last argument, even when there are no |
520 | additional arguments. | 596 | additional arguments. |
521 | 597 | ||
522 | Return @null{} on error, handle to daemon on success. | 598 | Return @mynull{} on error, handle to daemon on success. |
523 | @end deftypefun | 599 | @end deftypefun |
524 | 600 | ||
525 | 601 | ||
@@ -542,8 +618,8 @@ started with the right options for this call. | |||
542 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 618 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
543 | 619 | ||
544 | @c ----------------------------------------------------------- | 620 | @c ----------------------------------------------------------- |
545 | @node microhttpd inspect | 621 | @node microhttpd-inspect |
546 | @appendixsec Inspection | 622 | @chapter Implementing external @code{select} |
547 | 623 | ||
548 | 624 | ||
549 | @deftypefun int MHD_get_fdset (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd) | 625 | @deftypefun int MHD_get_fdset (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd) |
@@ -560,7 +636,7 @@ identifier. The variable must be set to zero before invoking this | |||
560 | function. | 636 | function. |
561 | 637 | ||
562 | Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are | 638 | Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are |
563 | invalid (example: @null{} pointers); this daemon was not started with | 639 | invalid (example: @mynull{} pointers); this daemon was not started with |
564 | the right options for this call. | 640 | the right options for this call. |
565 | @end deftypefun | 641 | @end deftypefun |
566 | 642 | ||
@@ -585,71 +661,8 @@ right now). | |||
585 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 661 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
586 | 662 | ||
587 | @c ----------------------------------------------------------- | 663 | @c ----------------------------------------------------------- |
588 | @node microhttpd requests | 664 | @node microhttpd-requests |
589 | @appendixsec Handling requests | 665 | @chapter Handling requests |
590 | |||
591 | |||
592 | @menu | ||
593 | * microhttpd handlers:: @uri{} specific handlers. | ||
594 | * microhttpd values:: Connection headers and small | ||
595 | @code{POST} data. | ||
596 | @end menu | ||
597 | |||
598 | |||
599 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | ||
600 | |||
601 | @c ------------------------------------------------------------ | ||
602 | @node microhttpd handlers | ||
603 | @appendixsubsec @uri{} specific handlers | ||
604 | |||
605 | |||
606 | @noindent | ||
607 | A set of callbacks can be registered in the state of a daemon | ||
608 | (@code{MHD_Daemon}) to handle request for specific sets of | ||
609 | resources. The set is selected by specifying the prefix string of the | ||
610 | @uri{}, example: | ||
611 | |||
612 | @example | ||
613 | /bookcase | ||
614 | @end example | ||
615 | |||
616 | @noindent | ||
617 | matches all of the following: | ||
618 | |||
619 | @example | ||
620 | /bookcase/book.html | ||
621 | /bookcase/pencil.html | ||
622 | /bookcase/strawberry.html | ||
623 | @end example | ||
624 | |||
625 | Handlers are stored in a linked list (managed with @cfunction{malloc} | ||
626 | and @cfunction{free}). Prefixes are compared with @cfunction{strcmp}. | ||
627 | |||
628 | |||
629 | @deftypefun int MHD_register_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls) | ||
630 | Register an access handler for all @uri{}s beginning with | ||
631 | @var{uri_prefix}, a zero-terminated @ascii{}-coded string. | ||
632 | |||
633 | Return @code{MRI_NO} if: the arguments are invalid (example: @null{} | ||
634 | pointers); a handler for this exact prefix already exists; an error | ||
635 | allocating memory happens. | ||
636 | @end deftypefun | ||
637 | |||
638 | |||
639 | @deftypefun int MHD_unregister_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls) | ||
640 | Unregister an access handler for the @uri{}s beginning with | ||
641 | @var{uri_prefix}. | ||
642 | |||
643 | Return @code{MHD_NO} if: the arguments are invalid (example: @null{} | ||
644 | pointers); a handler for this exact prefix is not known for this daemon. | ||
645 | @end deftypefun | ||
646 | |||
647 | |||
648 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | ||
649 | |||
650 | @c ------------------------------------------------------------ | ||
651 | @node microhttpd values | ||
652 | @appendixsubsec Connection headers and small @code{POST} data | ||
653 | 666 | ||
654 | 667 | ||
655 | @deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls) | 668 | @deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls) |
@@ -660,7 +673,7 @@ The @var{iterator} callback is invoked once for each header, with | |||
660 | iterated over; this can be less than the number of headers if, while | 673 | iterated over; this can be less than the number of headers if, while |
661 | iterating, @var{iterator} returns @code{MHD_NO}. | 674 | iterating, @var{iterator} returns @code{MHD_NO}. |
662 | 675 | ||
663 | @var{iterator} can be @null{}: in this case this function just counts | 676 | @var{iterator} can be @mynull{}: in this case this function just counts |
664 | and returns the number of headers. | 677 | and returns the number of headers. |
665 | @end deftypefun | 678 | @end deftypefun |
666 | 679 | ||
@@ -670,7 +683,7 @@ Get a particular header value. If multiple values match the @var{kind}, | |||
670 | return one of them (the ``first'', whatever that means). @var{key} must | 683 | return one of them (the ``first'', whatever that means). @var{key} must |
671 | reference a zero-terminated @ascii{}-coded string representing the | 684 | reference a zero-terminated @ascii{}-coded string representing the |
672 | header to look for: it is compared against the headers using | 685 | header to look for: it is compared against the headers using |
673 | @cfunction{strcasecmp}, so case is ignored. Return @null{} if no such | 686 | @cfunction{strcasecmp}, so case is ignored. Return @mynull{} if no such |
674 | item was found. | 687 | item was found. |
675 | @end deftypefun | 688 | @end deftypefun |
676 | 689 | ||
@@ -678,15 +691,15 @@ item was found. | |||
678 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 691 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
679 | 692 | ||
680 | @c ------------------------------------------------------------ | 693 | @c ------------------------------------------------------------ |
681 | @node microhttpd responses | 694 | @node microhttpd-responses |
682 | @appendixsec Building answers to responses | 695 | @chapter Building answers to responses |
683 | 696 | ||
684 | 697 | ||
685 | @menu | 698 | @menu |
686 | * microhttpd response enqueue:: Enqueuing a response. | 699 | * microhttpd-response enqueue:: Enqueuing a response. |
687 | * microhttpd response create:: Creating a response object. | 700 | * microhttpd-response create:: Creating a response object. |
688 | * microhttpd response headers:: Adding headers to a response. | 701 | * microhttpd-response headers:: Adding headers to a response. |
689 | * microhttpd response inspect:: Inspecting a response object. | 702 | * microhttpd-response inspect:: Inspecting a response object. |
690 | @end menu | 703 | @end menu |
691 | 704 | ||
692 | 705 | ||
@@ -709,8 +722,8 @@ responce and we finally destroy it only when the daemon shuts down. | |||
709 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 722 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
710 | 723 | ||
711 | @c ------------------------------------------------------------ | 724 | @c ------------------------------------------------------------ |
712 | @node microhttpd response enqueue | 725 | @node microhttpd-response enqueue |
713 | @appendixsubsec Enqueuing a response | 726 | @@section Enqueuing a response |
714 | 727 | ||
715 | 728 | ||
716 | @deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response) | 729 | @deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response) |
@@ -729,7 +742,7 @@ response to transmit. | |||
729 | @end table | 742 | @end table |
730 | 743 | ||
731 | Return @code{MHD_YES} on success or if message has been queued. Return | 744 | Return @code{MHD_YES} on success or if message has been queued. Return |
732 | @code{MHD_NO}: if arguments are invalid (example: @null{} pointer); on | 745 | @code{MHD_NO}: if arguments are invalid (example: @mynull{} pointer); on |
733 | error (i.e. reply already sent). | 746 | error (i.e. reply already sent). |
734 | @end deftypefun | 747 | @end deftypefun |
735 | 748 | ||
@@ -784,8 +797,8 @@ the @code{MHD_Response} object is released. | |||
784 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 797 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
785 | 798 | ||
786 | @c ------------------------------------------------------------ | 799 | @c ------------------------------------------------------------ |
787 | @node microhttpd response create | 800 | @node microhttpd-response create |
788 | @appendixsubsec Creating response objects | 801 | @@section Creating response objects |
789 | 802 | ||
790 | 803 | ||
791 | @deftypefun {struct MHD_Response *} MHD_create_response_from_callback (size_t size, unsigned int block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc) | 804 | @deftypefun {struct MHD_Response *} MHD_create_response_from_callback (size_t size, unsigned int block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc) |
@@ -812,7 +825,7 @@ extra argument to @var{crc}; | |||
812 | callback to call to free @var{crc_cls} resources. | 825 | callback to call to free @var{crc_cls} resources. |
813 | @end table | 826 | @end table |
814 | 827 | ||
815 | Return @null{} on error (i.e. invalid arguments, out of memory). | 828 | Return @mynull{} on error (i.e. invalid arguments, out of memory). |
816 | @end deftypefun | 829 | @end deftypefun |
817 | 830 | ||
818 | 831 | ||
@@ -837,7 +850,7 @@ handling of the embedded memory is responsibility of @mhd{}; @var{data} | |||
837 | can be released anytime after this call returns. | 850 | can be released anytime after this call returns. |
838 | @end table | 851 | @end table |
839 | 852 | ||
840 | Return @null{} on error (i.e. invalid arguments, out of memory). | 853 | Return @mynull{} on error (i.e. invalid arguments, out of memory). |
841 | @end deftypefun | 854 | @end deftypefun |
842 | 855 | ||
843 | 856 | ||
@@ -860,8 +873,8 @@ MHD_destroy_response(response); | |||
860 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 873 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
861 | 874 | ||
862 | @c ------------------------------------------------------------ | 875 | @c ------------------------------------------------------------ |
863 | @node microhttpd response headers | 876 | @node microhttpd-response headers |
864 | @appendixsubsec Adding headers to a response | 877 | @@section Adding headers to a response |
865 | 878 | ||
866 | 879 | ||
867 | @deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content) | 880 | @deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content) |
@@ -886,8 +899,8 @@ Delete a header line from the response. Return @code{MHD_NO} on error | |||
886 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 899 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
887 | 900 | ||
888 | @c ------------------------------------------------------------ | 901 | @c ------------------------------------------------------------ |
889 | @node microhttpd response inspect | 902 | @node microhttpd-response inspect |
890 | @appendixsubsec Inspecting a response object | 903 | @@section Inspecting a response object |
891 | 904 | ||
892 | 905 | ||
893 | @deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls) | 906 | @deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls) |
@@ -895,7 +908,7 @@ Get all of the headers added to a response. | |||
895 | 908 | ||
896 | Invoke the @var{iterator} callback for each header in the response, | 909 | Invoke the @var{iterator} callback for each header in the response, |
897 | using @var{iterator_cls} as first argument. Return number of entries | 910 | using @var{iterator_cls} as first argument. Return number of entries |
898 | iterated over. @var{iterator} can be @null{}: in this case the function | 911 | iterated over. @var{iterator} can be @mynull{}: in this case the function |
899 | just counts headers. | 912 | just counts headers. |
900 | 913 | ||
901 | @var{iterator} should not modify the its key and value arguments, unless | 914 | @var{iterator} should not modify the its key and value arguments, unless |
@@ -907,7 +920,7 @@ we know what we are doing. | |||
907 | Find and return a pointer to the value of a particular header from the | 920 | Find and return a pointer to the value of a particular header from the |
908 | response. @var{key} must reference a zero-terminated string | 921 | response. @var{key} must reference a zero-terminated string |
909 | representing the header to look for. The search is case sensitive. | 922 | representing the header to look for. The search is case sensitive. |
910 | Return @null{} if header does not exist or @var{key} is @null{}. | 923 | Return @mynull{} if header does not exist or @var{key} is @mynull{}. |
911 | 924 | ||
912 | We should not modify the value, unless we know what we are doing. | 925 | We should not modify the value, unless we know what we are doing. |
913 | @end deftypefun | 926 | @end deftypefun |
@@ -916,35 +929,33 @@ We should not modify the value, unless we know what we are doing. | |||
916 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 929 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
917 | 930 | ||
918 | @c ------------------------------------------------------------ | 931 | @c ------------------------------------------------------------ |
919 | @node microhttpd post | 932 | @node microhttpd-post |
920 | @appendixsec Adding a @code{POST} processor | 933 | @chapter Adding a @code{POST} processor |
921 | 934 | ||
922 | 935 | ||
923 | @menu | 936 | @menu |
924 | * microhttpd post api:: Programming interface for the | 937 | * microhttpd-post api:: Programming interface for the |
925 | @code{POST} processor. | 938 | @code{POST} processor. |
926 | @end menu | 939 | @end menu |
927 | 940 | ||
928 | 941 | ||
929 | @noindent | 942 | @noindent |
930 | When a small amount of data comes from a client's @code{POST} request: | 943 | @mhd{} provides the post procesor API to make it easier for applications to |
931 | the data is available through the values interface. @ref{microhttpd | 944 | parse the data of a client's @code{POST} request: the |
932 | values}, for details. In this case @mhd{} invokes | ||
933 | @code{MHD_AccessHandlerCallback} only once and the callback must process | ||
934 | all the data during that invocation. | ||
935 | |||
936 | When a big amount of data comes from a client's @code{POST} request: the | ||
937 | @code{MHD_AccessHandlerCallback} will be invoked multiple times to | 945 | @code{MHD_AccessHandlerCallback} will be invoked multiple times to |
938 | process data as it arrives; at each invocation a new chunk of data must | 946 | process data as it arrives; at each invocation a new chunk of data must |
939 | be processed. The arguments @var{upload_data} and @var{upload_data_size} | 947 | be processed. The arguments @var{upload_data} and @var{upload_data_size} |
940 | are used to reference the chunk of data. | 948 | are used to reference the chunk of data. |
941 | 949 | ||
942 | When @code{MHD_AccessHandlerCallback} is invoked for a new connection: | 950 | When @code{MHD_AccessHandlerCallback} is invoked for a new connection: |
943 | its @code{*@var{con_cls}} argument is set to @null{}. When @code{POST} | 951 | its @code{*@var{con_cls}} argument is set to @mynull{}. When @code{POST} |
944 | data comes in the upload buffer it is @strong{mandatory} to use the | 952 | data comes in the upload buffer it is @strong{mandatory} to use the |
945 | @var{con_cls} to hold data or to mark an ongoing process. | 953 | @var{con_cls} to store a reference to per-connection data. The fact |
954 | that the pointer was initially @mynull{} can be used to detect that | ||
955 | this is a new request. | ||
946 | 956 | ||
947 | To detect that a new connection has come with the @code{POST} method: | 957 | One method to detect that a new connection was established is |
958 | to set @code{*con_cls} to anunused integer: | ||
948 | 959 | ||
949 | @example | 960 | @example |
950 | int | 961 | int |
@@ -956,10 +967,9 @@ access_handler (void *cls, | |||
956 | void **con_cls) | 967 | void **con_cls) |
957 | @{ | 968 | @{ |
958 | static int old_connection_marker; | 969 | static int old_connection_marker; |
959 | int new_connection = (NULL == *con_cls); | 970 | int new_connection = (MYNULL == *con_cls); |
960 | int method_is_post = strcmp("POST",method); | ||
961 | 971 | ||
962 | if (new_connection && method_is_post) | 972 | if (new_connection) |
963 | @{ | 973 | @{ |
964 | /* new connection with POST */ | 974 | /* new connection with POST */ |
965 | *con_cls = &old_connection_marker; | 975 | *con_cls = &old_connection_marker; |
@@ -970,12 +980,10 @@ access_handler (void *cls, | |||
970 | @end example | 980 | @end example |
971 | 981 | ||
972 | @noindent | 982 | @noindent |
973 | in this example the value of @code{*con_cls} is just an unused pointer | 983 | In contrast to the previous example, for @code{POST} requests in particular, |
974 | to an unused integer: its purpose is to make @code{*con_cls} different | 984 | it is more common to use the value of @code{*con_cls} to keep track of |
975 | from @null{}. When serious processing of @code{POST} data is needed: it | 985 | actual state used during processing, such as the post processor (or a |
976 | can be a pointer to a dynamically allocated data structure. | 986 | struct containing a post processor): |
977 | |||
978 | To detect that @code{POST} data is in the upload buffer: | ||
979 | 987 | ||
980 | @example | 988 | @example |
981 | int | 989 | int |
@@ -986,156 +994,38 @@ access_handler (void *cls, | |||
986 | const char *upload_data, unsigned int *upload_data_size, | 994 | const char *upload_data, unsigned int *upload_data_size, |
987 | void **con_cls) | 995 | void **con_cls) |
988 | @{ | 996 | @{ |
989 | static int old_connection_marker; | 997 | struct MHD_PostProcessor * pp = *con_cls; |
990 | int new_connection = (NULL == *con_cls); | ||
991 | int method_is_post = strcmp("POST",method); | ||
992 | 998 | ||
993 | if (new_connection && method_is_post) | 999 | if (pp == NULL) |
994 | @{ | 1000 | @{ |
995 | int data_in_upload_buffer = (0 != *upload_data_size); | 1001 | pp = MHD_create_post_processor(connection, ...); |
996 | 1002 | *con_cls = pp; | |
997 | if (data_in_upload_buffer) | 1003 | return MHD_YES; |
998 | @{ | ||
999 | *con_cls = &old_connection_marker; | ||
1000 | /* POST data in the buffer */ | ||
1001 | @} | ||
1002 | else | ||
1003 | /* POST data accessible with the values API */ | ||
1004 | @} | ||
1005 | |||
1006 | ... | ||
1007 | @} | ||
1008 | @end example | ||
1009 | |||
1010 | |||
1011 | At each invocation there are two options: | ||
1012 | |||
1013 | @enumerate | ||
1014 | @item | ||
1015 | the callback can process the whole chunk by itself; every time @mhd{} | ||
1016 | invokes it a new chunk is fully processed; with this mode the callback | ||
1017 | has to @code{*upload_data_size = 0} before returning @code{MHD_YES}; | ||
1018 | |||
1019 | @item | ||
1020 | the callback can process a section of the chunk by itself; every time | ||
1021 | @mhd{} invokes it the buffer holds the old data as well as new data | ||
1022 | coming from the client; with this mode the callback has to set | ||
1023 | @code{*upload_data_size} to the numbe of bytes still to process before | ||
1024 | returning @code{MHD_YES}; | ||
1025 | |||
1026 | example: @mhd{} invokes the callback with @code{100 == | ||
1027 | *upload_data_size}; the callback processes the first 80 bytes and before | ||
1028 | returning the callback sets @code{*upload_data_size = 20}; the last | ||
1029 | unprocessed 20 bytes will be the first 20 at the next invocation; | ||
1030 | |||
1031 | @item | ||
1032 | when a new connection with @code{POST} data in the buffer comes: the | ||
1033 | callback allocates a PostProcessor and hand to it the responsibility of | ||
1034 | processing data; a pointer to the PostProcessor structure is saved in | ||
1035 | @code{*con_cls}, so that it is available at each subsequent invocation; | ||
1036 | |||
1037 | the post processor data can be freed by a later invocation to an | ||
1038 | appropriate callback. | ||
1039 | @end enumerate | ||
1040 | |||
1041 | |||
1042 | Let's see how to implement strategy 1: | ||
1043 | |||
1044 | @example | ||
1045 | int | ||
1046 | access_handler (void *cls, | ||
1047 | struct MHD_Connection * connection, | ||
1048 | const char *url, | ||
1049 | const char *method, const char *version, | ||
1050 | const char *upload_data, unsigned int *upload_data_size, | ||
1051 | void **con_cls) | ||
1052 | @{ | ||
1053 | static int old_connection_marker; | ||
1054 | int new_connection = (NULL == *con_cls); | ||
1055 | int method_is_post = strcmp("POST",method); | ||
1056 | |||
1057 | if (new_connection && method_is_post) | ||
1058 | @{ | ||
1059 | int data_in_upload_buffer = (0 != *upload_data_size); | ||
1060 | |||
1061 | if (data_in_upload_buffer) | ||
1062 | @{ | ||
1063 | *con_cls = &old_connection_marker; | ||
1064 | @} | ||
1065 | else | ||
1066 | @{ | ||
1067 | /* POST data accessible with the values API */ | ||
1068 | return MHD_YES; | ||
1069 | @} | ||
1070 | @} | 1004 | @} |
1071 | 1005 | if (*upload_data_size) | |
1072 | if (&old_connection_marker == *con_cls) | ||
1073 | @{ | 1006 | @{ |
1074 | consume_data(upload_data, *upload_data_size); | 1007 | MHD_post_process(pp, upload_data, *upload_data_size); |
1075 | *upload_data_size = 0; | 1008 | *upload_data_size = 0; |
1076 | return MHD_YES; | 1009 | return MHD_YES; |
1077 | @} | 1010 | @} |
1078 | 1011 | else | |
1079 | /* process other methods */ | ||
1080 | return MHD_YES; | ||
1081 | @} | ||
1082 | @end example | ||
1083 | |||
1084 | Let's see how to implement strategy 2: | ||
1085 | |||
1086 | @example | ||
1087 | int | ||
1088 | access_handler (void *cls, | ||
1089 | struct MHD_Connection * connection, | ||
1090 | const char *url, | ||
1091 | const char *method, const char *version, | ||
1092 | const char *upload_data, unsigned int *upload_data_size, | ||
1093 | void **con_cls) | ||
1094 | @{ | ||
1095 | static int old_connection_marker; | ||
1096 | int new_connection = (NULL == *con_cls); | ||
1097 | int method_is_post = strcmp("POST",method); | ||
1098 | |||
1099 | if (new_connection && method_is_post) | ||
1100 | @{ | 1012 | @{ |
1101 | int data_in_upload_buffer = (0 != *upload_data_size); | 1013 | return MHD_queue_response(...); |
1102 | |||
1103 | if (data_in_upload_buffer) | ||
1104 | @{ | ||
1105 | *con_cls = &old_connection_marker; | ||
1106 | @} | ||
1107 | else | ||
1108 | @{ | ||
1109 | /* POST data accessible with the values API */ | ||
1110 | return MHD_YES; | ||
1111 | @} | ||
1112 | @} | 1014 | @} |
1113 | |||
1114 | if (&old_connection_marker == *con_cls) | ||
1115 | @{ | ||
1116 | int number_of_bytes_to_consume = 100; | ||
1117 | |||
1118 | if (number_of_bytes_to_consume > *upload_data_size) | ||
1119 | number_of_bytes_to_consume = *upload_data_size; | ||
1120 | |||
1121 | consume_some_data(upload_data, number_of_bytes_to_consume); | ||
1122 | *upload_data_size -= number_of_bytes_to_consume; | ||
1123 | return MHD_YES; | ||
1124 | @} | ||
1125 | |||
1126 | /* process other methods */ | ||
1127 | return MHD_YES; | ||
1128 | @} | 1015 | @} |
1129 | |||
1130 | @end example | 1016 | @end example |
1131 | 1017 | ||
1018 | Note that the callback from @code{MHD_OPTION_NOTIFY_COMPLETED} | ||
1019 | should be used to destroy the post processor. This cannot be | ||
1020 | done inside of the access handler since the connection may not | ||
1021 | always terminate normally. | ||
1132 | 1022 | ||
1133 | 1023 | ||
1134 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 1024 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1135 | 1025 | ||
1136 | @c ------------------------------------------------------------ | 1026 | @c ------------------------------------------------------------ |
1137 | @node microhttpd post api | 1027 | @node microhttpd-post api |
1138 | @appendixsubsec Programming interface for the @code{POST} processor | 1028 | @@section Programming interface for the @code{POST} processor |
1139 | 1029 | ||
1140 | 1030 | ||
1141 | 1031 | ||
@@ -1155,13 +1045,13 @@ should be sufficient; do @strong{NOT} use a value smaller than 256; | |||
1155 | 1045 | ||
1156 | @item iterator | 1046 | @item iterator |
1157 | iterator to be called with the parsed data; must @strong{NOT} be | 1047 | iterator to be called with the parsed data; must @strong{NOT} be |
1158 | @null{}; | 1048 | @mynull{}; |
1159 | 1049 | ||
1160 | @item iterator_cls | 1050 | @item iterator_cls |
1161 | custom value to be used as first argument to @var{iterator}. | 1051 | custom value to be used as first argument to @var{iterator}. |
1162 | @end table | 1052 | @end table |
1163 | 1053 | ||
1164 | Return @null{} on error (out of memory, unsupported encoding), otherwise | 1054 | Return @mynull{} on error (out of memory, unsupported encoding), otherwise |
1165 | a PP handle. | 1055 | a PP handle. |
1166 | @end deftypefun | 1056 | @end deftypefun |
1167 | 1057 | ||
@@ -1196,3 +1086,26 @@ Release PostProcessor resources. | |||
1196 | 1086 | ||
1197 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 1087 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1198 | 1088 | ||
1089 | |||
1090 | @c ********************************************************** | ||
1091 | @c ******************* Appendices ************************* | ||
1092 | @c ********************************************************** | ||
1093 | |||
1094 | @include lgpl.texi | ||
1095 | |||
1096 | @node Concept Index | ||
1097 | @unnumbered Concept Index | ||
1098 | |||
1099 | @printindex cp | ||
1100 | |||
1101 | @node Function and Data Index | ||
1102 | @unnumbered Function and Data Index | ||
1103 | |||
1104 | @printindex fn | ||
1105 | |||
1106 | @node Type Index | ||
1107 | @unnumbered Type Index | ||
1108 | |||
1109 | @printindex tp | ||
1110 | |||
1111 | @bye | ||