[libmicrohttpd2] branch master updated: more work on chapters 1+2

[Admin]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository libmicrohttpd2.

The following commit(s) were added to refs/heads/master by this push:
     new b6c1d8c  more work on chapters 1+2
b6c1d8c is described below

commit b6c1d8cd5412123e27689eb4ee33da0f178b4a76
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon Feb 10 23:57:34 2025 +0100

    more work on chapters 1+2
---
 doc/libmicrohttpd2.texi      |  43 ++++---
 doc/manual/callbacks.inc     |  82 --------------
 doc/manual/constants.inc     |  16 ---
 doc/manual/init.inc          | 264 ++++++++++++++++++++++++++++++++++++-------
 doc/manual/introduction.inc  | 157 ++++++++++++++++++-------
 doc/manual/introspection.inc |   2 -
 doc/manual/structs.inc       |  19 +---
 7 files changed, 357 insertions(+), 226 deletions(-)

diff --git a/doc/libmicrohttpd2.texi b/doc/libmicrohttpd2.texi
index 10181b6..b80a9d3 100644
--- a/doc/libmicrohttpd2.texi
+++ b/doc/libmicrohttpd2.texi
@@ -50,23 +50,23 @@ Free Documentation License".
 @node Top
 @top The GNU libmicrohttpd2 Library
 @insertcopying
-end ifnottex
+@end ifnottex
+
 
 @menu
 * libmicrohttpd2-introduction::     Introduction.
-* libmicrohttpd2-structures::       Structures.
-* libmicrohttpd2-constants::        Constants.
-* libmicrohttpd2-callbacks::        Callbacks.
 * libmicrohttpd2-init::             Starting and stopping the server.
-* libmicrohttpd2-select::           Implementing external @code{select}.
-* libmicrohttpd2-requests::         Handling requests.
-* libmicrohttpd2-responses::        Building responses to requests.
-* libmicrohttpd2-flow::             Flow control.
-* libmicrohttpd2-dauth::            Utilizing Authentication.
-* libmicrohttpd2-post::             Adding a @code{POST} processor.
-* libmicrohttpd2-info::             Obtaining and modifying status information.
+* libmicrohttpd2-doptions::         Configuring your HTTP server.
+* libmicrohttpd2-threadmodes::      Using different thread modes.
+* libmicrohttpd2-requests::         Accessing client request data.
+* libmicrohttpd2-action::           Acting on HTTP requests.
+* libmicrohttpd2-responses::        Generating HTTP responses.
+* libmicrohttpd2-auth::             Utilizing HTTP authentication.
+* libmicrohttpd2-post::             Parsing @code{POST} data.
+* libmicrohttpd2-upgrade::          Upgrading HTTP/1.1 connections.
+* libmicrohttpd2-introspection::    Obtaining status information.
 * libmicrohttpd2-util::             Utilities.
-* libmicrohttpd2-websocket::        Websockets.
+* libmicrohttpd2-flow::             Flow control?
 
 Appendices
 
@@ -84,25 +84,20 @@ Indices
 * Type Index::                  Index of data types.
 @end menu
 
+
 @node libmicrohttpd2-introduction
 @chapter Introduction
 @include manual/introduction.inc
 
-@node libmicrohttpd2-structures
-@chapter Structures
-@include manual/structs.inc
+@node libmicrohttpd2-init
+@chapter Starting and stopping the HTTP server
+@include manual/init.inc
+
+
+@bye
 
-@node libmicrohttpd2-constants
-@chapter Constants
-@include manual/constants.inc
 
-@node libmicrohttpd2-callbacks
-@chapter Callbacks
-@include manual/callbacks.inc
 
-@node libmicrohttpd2-init
-@chapter Starting and stopping the server
-@include manual/init.inc
 
 @node libmicrohttpd2-select
 @chapter Implementing external @code{select}
diff --git a/doc/manual/callbacks.inc b/doc/manual/callbacks.inc
index 304b359..38c8fb3 100644
--- a/doc/manual/callbacks.inc
+++ b/doc/manual/callbacks.inc
@@ -15,87 +15,6 @@ length of the address information.
 @end deftypefn
 
 
-@deftypefn {Function Pointer} enum MHD_Result {*MHD_AccessHandlerCallback} 
(void *cls, struct MHD_Connection * connection, const char *url, const char 
*method, const char *version, const char *upload_data, size_t 
*upload_data_size, void **req_cls)
-Invoked in the context of a connection to answer a request from the
-client.  This callback must call MHD functions (example: the
-@code{MHD_Response} ones) to provide content to give back to the client
-and return an HTTP status code (i.e. @code{200} for OK, @code{404},
-etc.).
-
-@ref{microhttpd-post}, for details on how to code this callback.
-
-Must return @code{MHD_YES} if the connection was handled successfully,
-@code{MHD_NO} if the socket must be closed due to a serious error while
-handling the request
-
-@table @var
-@item cls
-custom value selected at callback registration time;
-
-@item url
-the URL requested by the client;
-
-@item method
-the HTTP method used by the client (@code{GET}, @code{PUT},
-@code{DELETE}, @code{POST}, etc.);
-
-@item version
-the HTTP version string (i.e. @code{HTTP/1.1});
-
-@item upload_data
-the data being uploaded (excluding headers):
-@cindex POST method
-@cindex PUT method
-
-@code{POST} data @strong{will} be made available
-incrementally in @var{upload_data}; even if @code{POST}
-data is available, the first time the callback is
-invoked there won't be upload data, as this is done
-just after MHD parses the headers.  If supported by
-the client and the HTTP version, the application can
-at this point queue an error response to possibly
-avoid the upload entirely. If no response is generated,
-MHD will (if required) automatically send a 100 CONTINUE
-reply to the client.
-
-Afterwards, POST data will be passed to the callback
-to be processed incrementally by the application. The
-application may return @code{MHD_NO} to forcefully
-terminate the TCP connection without generating a
-proper HTTP response. Once all of the upload data has
-been provided to the application, the application
-will be called again with 0 bytes of upload data.
-At this point, a response should be queued to complete
-the handling of the request.
-
-@item upload_data_size
-set initially to the size of the @var{upload_data} provided; this
-callback must update this value to the number of bytes @strong{NOT}
-processed; unless external select is used, the callback maybe
-required to process at least some data.  If the callback fails to
-process data in multi-threaded or internal-select mode and if the
-read-buffer is already at the maximum size that MHD is willing to
-use for reading (about half of the maximum amount of memory allowed
-for the connection), then MHD will abort handling the connection
-and return an internal server error to the client.  In order to
-avoid this, clients must be able to process upload data incrementally
-and reduce the value of @code{upload_data_size}.
-
-@item req_cls
-reference to a pointer, initially set to @code{NULL}, that this callback can
-set to some address and that will be preserved by MHD for future
-calls for this request;
-
-since the access handler may be called many times (i.e., for a
-@code{PUT}/@code{POST} operation with plenty of upload data) this allows
-the application to easily associate some request-specific state;
-
-if necessary, this state can be cleaned up in the global
-@code{MHD_RequestCompletedCallback} (which can be set with the
-@code{MHD_OPTION_NOTIFY_COMPLETED}).
-@end table
-@end deftypefn
-
 
 @deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, 
struct MHD_Connectionconnection, void **req_cls, enum 
MHD_RequestTerminationCode toe)
 Signature of the callback used by MHD to notify the application about
@@ -337,4 +256,3 @@ size of buffer in bytes.
 Return the number of generated random bytes.
 The return value should usually equal to buf_len.
 @end deftypefn
-
diff --git a/doc/manual/constants.inc b/doc/manual/constants.inc
index 5a71394..86295e9 100644
--- a/doc/manual/constants.inc
+++ b/doc/manual/constants.inc
@@ -28,21 +28,6 @@ The most common value is @code{MHD_SC_OK} (0)
 which indicates a successful operation.
 
 
-@deftp {Enumeration} MHD_HTTP_Method
-
-Represents canonical HTTP methods as per RFC 9110. Non-canonical HTTP
-methods are given the special value @code{MHD_HTTP_METHOD_OTHER}. In
-this case, it is up to the application to interpret the HTTP method
-(which is then also exposed as a string value).
-
-The convenience function @code{MHD_http_method_to_string()}
-can be used to convert members of this enumeration to
-a string value.
-
-Various additional string constants are defined for
-HTTP methods from a range of RFCs, see constants
-with the prefix @code{MHD_HTTP_METHOD_STR_}.
-
 
 @deftp {Enumeration} MHD_HTTP_PostEncoding
 
@@ -733,4 +718,3 @@ may follow from the sender of the close frame.
 
 @end table
 @end deftp
-
diff --git a/doc/manual/init.inc b/doc/manual/init.inc
index afb8f7b..284a38c 100644
--- a/doc/manual/init.inc
+++ b/doc/manual/init.inc
@@ -1,107 +1,287 @@
+This chapter explains the key functions of MHD to create, start,
+quiesce and destroy an HTTP server, as well as how to configure
+global logging to receive more detailed messages when something
+goes really wrong inside of MHD.
+
+@node libmicrohttpd-init-panic
+@section Setting up a panic handler
+
+@code{MHD_PanicCallback} is the type of a function that MHD
+calls when it encounters an error that it cannot handle. This
+should always be indicative of a serious bug, be it a hardware
+failure (such as a bit-flip in RAM or a broken CPU) or a bug
+in the application (for example, memory corruption or a
+failed assertion). MHD will not cause a panic in case of
+normal operation or when there would be a safe way to continue
+the execution.
+
 @deftypefn {Function Pointer} enum MHD_Result {*MHD_PanicCallback} (void *cls, 
const char *file, const char *func, unsigned int line, const char *message)
-Invoked in the context of a serious error condition. The default action is to 
print an error message and @code{abort()}. The callback should not return. Some 
parameters could be empty strings (with zero-termination at zero position),
+Invoked in the context of a serious error condition. The callback should not 
return. Some parameters could be empty strings (with zero-termination at zero 
position),
 especially if MHD is built without support for log messages.
 @table @var
 @item cls
-custom value selected at callback registration time;
+custom value provided by the application at callback registration time;
 @item file
-name of the source file where the error occured
+name of the source file where the error occured;
 @item func
-function in the source where the error occured
+function in the source where the error occured;
 @item line
-line in the source file where the error occured
+line in the source file where the error occured;
 @item message
-message describing the error
+message describing the error;
 @end table
 @end deftypefn
 
+MHD comes with a default panic action, which is to print an error
+message and call @code{abort()} to terminate the process.
+Applications can use @code{MHD_lib_set_panic_func()} to change this
+behavior. However, applications must always terminate the process
+inside of the panic callback (but they could use @code{exit()} or
+@code{_exit()} or some other way to terminate the process). Note that
+the panic function is @emph{expected} to be called in a situation
+where the process is in an @emph{unsafe} state, thus even the default
+behavior of calling @code{fprintf()} could be dangerous as it may
+enable an attacker to further exploit whatever bug caused the panic in
+the first place.
 
 @deftypefun {void} MHD_lib_set_panic_func (MHD_PanicCallback cb, void *cls)
 Set a handler for fatal errors.
 
 @table @var
 @item cb
-function to call if MHD encounters a fatal internal error.  If no handler was 
set explicitly, MHD will call @code{abort}.
+function to call if MHD encounters a fatal internal error.  If no handler was 
set explicitly, MHD will log an error and call @code{abort()}.
 
 @item cls
-closure argument for cb; the other arguments are the name of the source file, 
line number and a string describing the nature of the fatal error (which can be 
@code{NULL})
+closure argument for @var{cb}; the other arguments are the name of the source 
file, line number and a string describing the nature of the fatal error (which 
can be @code{NULL})
 @end table
 @end deftypefun
 
+@node libmicrohttpd-init-create
+@section Creating an HTTP daemon
+
+The @code{MHD_daemon_create()} function creates an @code{struct MHD_Daemon}.
+
+@deftp {C Struct} MHD_Daemon
+Handle for an HTTP daemon. A daemon contains the MHD configuration
+and state to listening on a socket for HTTP clients and handle
+their requests.
+@end deftp
+
+An application can in principle create multiple daemons, for example
+to listen on both port 80 and port 443. Each daemon handles request
+from at most one @code{listen()} socket.
+
 @deftypefun {struct MHD_Daemon *} MHD_daemon_create (MHD_RequestCallback 
req_cb, void *req_cb_cls)
 Create a new HTTP daemon object. Does not actually start
-the HTTP server.
-
+the HTTP daemon.
 @table @var
 @item req_cb
 Function to call to handle each HTTP request;
 
 @item req_cb_cls
-closure to pass to the @code{req_cb};
+closure to pass to the @var{req_cb};
 @end table
 
 Returns @code{NULL} on error (usually out-of-memory),
 handle to daemon on success.
 @end deftypefun
 
+When creating an HTTP daemon the application must pass the address of
+a function of type @code{MHD_RequestCallback} which MHD will call for
+each HTTP request that daemon receives from the network.
 
-@deftypefun MHD_socket MHD_quiesce_daemon (struct MHD_Daemon *daemon)
-@cindex quiesce
-Stop accepting connections from the listening socket.  Allows clients
-to continue processing, but stops accepting new connections.  Note
-that the caller is responsible for closing the returned socket;
-however, if MHD is run using threads (anything but external select
-mode), it must not be closed until AFTER @code{MHD_stop_daemon} has
-been called (as it is theoretically possible that an existing thread
-is still using it).
+@deftypefn {Function Pointer} struct MHD_Action * {*MHD_RequestCallback} (void 
*cls, struct MHD_Request *request, const struct MHD_String *path, enum 
MHD_HTTP_Method method, uint_fast64_t upload_size)
+Functions of this type are invoked by MHD whenever it received an HTTP
+request and needs to handle it.  Implementations must call MHD
+functions to create a @code{struct MHD_Action} which informs MHD about
+the next steps to take to handle the request.
+
+@ref{libmicrohttpd-actions} explains in more detail how to create the
+various possible actions. It is also possible to return @code{NULL},
+in which case MHD will close the HTTP connection without returning
+anything (not even an error message).  This can be used if the socket
+must be closed due to a serious error while handling the request (such
+as being out-of-memory).
+
+@table @var
+@item cls
+custom value provided by the application to @code{MHD_daemon_create()};
+
+@item path
+the PATH component of the HTTP URL requested by the client. Empty
+if the request was just for ``http://domain``, otherwise
+starting with ``/``.
+
+@item method
+the HTTP method used by the client;
+
+@item upload_size
+number of bytes of data that the client intends to upload
+in the request body; a special value of @code{MHD_SIZE_UNKNOWN}
+is provided if the client indicated the use of chunked encoding
+and the final upload size is not yet known;
+@end table
+@end deftypefn
+
+The HTTP @var{method} is not provided as a string as comparing
+strings is generally inefficient for the application. Furthermore,
+by providing an enumeration value applications often can avoid
+implementing case-insensitive ASCII string comparissons. However,
+the enumeration only works for HTTP methods specified in RFC 9110.
+
+@deftp {Enumeration} MHD_HTTP_Method
+
+Represents canonical HTTP methods as per RFC 9110.
+
+@table @code
+@item MHD_HTTP_METHOD_GET
+ "GET". Safe. Idempotent.  RFC9110, Section 9.3.1.
+
+@item MHD_HTTP_METHOD_HEAD
+"HEAD". Safe. Idempotent.  RFC9110, Section 9.3.2.
+
+@item MHD_HTTP_METHOD_POST
+"POST". Not safe. Not idempotent. RFC9110, Section 9.3.3.
+
+@item MHD_HTTP_METHOD_PUT
+"PUT". Not safe. Idempotent. RFC9110, Section 9.3.4.
+
+@item MHD_HTTP_METHOD_DELETE
+"DELETE". Not safe. Idempotent. RFC9110, Section 9.3.5.
+
+@item MHD_HTTP_METHOD_CONNECT
+"CONNECT". Not safe. Not idempotent. RFC9110, Section 9.3.6.
 
-This function is useful in the special case that a listen socket
-is to be migrated to another process (i.e. a newer version of the
-HTTP server) while existing connections should continue to be
-processed until they are finished.
+@item MHD_HTTP_METHOD_OPTIONS
+"OPTIONS". Safe. Idempotent. RFC9110, Section 9.3.7.
 
-Return @code{-1} on error (daemon not listening), the handle to the
-listen socket otherwise.
+@item MHD_HTTP_METHOD_TRACE
+"TRACE". Safe.  Idempotent. RFC9110, Section 9.3.8.
 
+@item MHD_HTTP_METHOD_ASTERISK
+ "*". Not safe. Not idempotent. RFC9110, Section 18.2.
+
+@item MHD_HTTP_METHOD_OTHER
+Non-canonical HTTP method. If an application wants to
+support non-canonical HTTP methods, the application
+must request the method's value by passing
+@code{MHD_REQUEST_INFO_DYNAMIC_HTTP_METHOD_STR}
+to @code{MHD_request_get_info_dynamic()}.
+@xref{libmicrohttpd2-requests-introspection}.
+
+@end table
+@end deftp
+
+The convenience function @code{MHD_http_method_to_string()}
+can be used to convert members of this enumeration to
+a string value.
+
+@deftypefun const struct MHD_String * MHD_http_method_to_string (enum 
MHD_HTTP_Method method)
+Get text version of the method name.
+
+Returns a pointer (!) to the HTTP method as a string.
+@code{NULL} is returned if @var{method} is @code{MHD_HTTP_METHOD_OTHER}.
+
+@table @var
+@item method
+the method to get the text version for
+
+@end table
 @end deftypefun
 
+Various additional string constants for HTTP methods are defined in
+the @code{microhttpd2.h} header for HTTP methods from a wide range of
+RFCs. Check the header for constants with the prefix
+@code{MHD_HTTP_METHOD_STR_}.
+
+@node libmicrohttpd-init-start
+@section Starting an HTTP daemon
+
+After creating an MHD daemon, applications will typically configure
+various optional features, such as support for TLS.
+@ref{libmicrohttpd-doptions} explains how to set the various options.
+Once the daemon is correctly configured, applications can start
+processing client requests using @code{MHD_daemon_start()}.
 
 @deftypefun enum MHD_StatusCode MHD_daemon_start (struct MHD_Daemon *daemon)
-Starts an HTTP daemon. Checks that the required options are
-all set and consistent, initializes the TLS library (if enabled), creates the 
listen socket and launches the internal threads (if configured as such).
+Starts an HTTP daemon. Checks that options are consistent,
+initializes the TLS library (if enabled),
+creates the listen socket (if not disabled) and
+launches the internal threads (if configured to do so).
 
 @table @var
 @item daemon
 Handle to the HTTP daemon to start. Must be configured
-but not yet started.
+but not have been started previously.
 @end table
 
-Return @code{MHD_SC_OK} on success, otherwise an error code indicative of the 
problem.
-listen socket otherwise.
+Returns @code{MHD_SC_OK} on success, otherwise an error code indicative of the 
problem.
 @end deftypefun
 
-@deftypefun MHD_Socket MHD_daemon_quiesce (struct MHD_Daemon *daemon)
-Stop accepting new connections at a daemon, but continue to process 
connections that were already accepted.
+Note that if you configured the daemon to use an
+@emph{external} event loop, calling @code{MHD_daemon_start()}
+is not sufficient to actually start processing client requests.
+In this case, you must also integrate MHD into your event loop.
+@xref{libmicrohttpd-threadmodes-external}.
+
+
+@node libmicrohttpd-init-quiesce
+@section Quiescing an HTTP daemon
+
+Quiescing an HTTP daemon prevents it from further accepting new
+connections, but allows it to finish handling existing clients.  This
+is useful to minimize the disruptions when gracefully shutting down,
+restarting or reloading an HTTP service.
+
+@deftypefun MHD_Socket MHD_quiesce_daemon (struct MHD_Daemon *daemon)
+@cindex quiesce
+Stop accepting connections from the listening socket.  Allows clients
+to continue processing, but stops accepting new connections.
 
 @table @var
 @item daemon
-Handle to the HTTP daemon to quiesce. Must be started.
+Handle to the HTTP daemon to quiesce. The daemon should have been
+started before.
 @end table
 
-Return listen socket (to be closed by caller) on success,
-@code{MHD_INVALID_SOCKET} if the daemon was already no
-longer listening (or was never started, or has no
-listen socket).
+The returned socket is the listen socket of the daemon.  This value
+can be useful in the special case that a listen socket is to be
+migrated to another process (i.e. a newer version of the HTTP server).
+The caller is made responsible for ultimately closing the returned
+socket; however, if MHD is run using threads (anything but external
+select mode), it @strong{must not} be closed until @emph{after}
+@code{MHD_daemon_destroy()} has been called (as it is theoretically
+possible that an existing thread is still using it).
+
+A value of @code{-1} is returned if either the daemon was not
+started or was not listening on a socket.
 @end deftypefun
 
+@cindex MHD_Socket
+@deftp {Typedef} MHD_Socket
+
+The type @code{MHD_Socket} is platform-dependent:
+@code{MHD_Socket} is simply an @code{int} on UNIX systems, while on
+W32 it is a @code{SOCKET}.
+@end deftp
+
+
+@node libmicrohttpd-init-destroy
+@section Destroying an HTTP daemon
+
+Destroying an HTTP daemon using @code{MHD_daemon_destroy()}
+immediately stops all MHD processing of associated requests and frees
+all associated resources. Applications do @emph{not} have to call
+@code{MHD_daemon_quiesce()} before destroying a daemon: if the daemon
+was not quiesced first, the listen socket will still be closed and all
+ongoing requests will simply be terminated hard by closing the
+connections.
+
 @deftypefun void MHD_daemon_destroy (struct MHD_Daemon *daemon)
-Shutdown and destroy an HTTP daemon. Frees all 
+Shutdown and destroy an HTTP daemon. Frees all
 resources still associated with the daemon.
 @table @var
 @item daemon
 Handle to the HTTP daemon to destroy.
 @end table
 @end deftypefun
-
-
-
diff --git a/doc/manual/introduction.inc b/doc/manual/introduction.inc
index 650d253..633056e 100644
--- a/doc/manual/introduction.inc
+++ b/doc/manual/introduction.inc
@@ -1,15 +1,17 @@
 @noindent
-MHD is a small HTTP daemon library, implementing the server-side
+MHD is a small HTTP daemon library implementing the server-side
 functionality of the HTTP protocol. Many of its features are
 optional and can be turned off using compiler flags. Features
 include:
 
 @itemize @bullet
-@item HTTP 1.0, HTTP/1.1 and (soon) HTTP2 support
+@item Supports HTTP 1.0, HTTP/1.1 and (soon) HTTP2
 @item Basic and digest authentication
-@item TLS via OpenSSL or libgnutls
+@item TLS via OpenSSL or libgnutls (mbedTLS planned)
 @item Websockets
 @item Different threading modes (select, poll, epoll, thread-per-connection, 
thread-pool)
+@item Stream processing (arbitrary size uploads)
+@item Chunked encoding, HTTP pipelining
 @item Limiting connections per client IP address
 @item Use of @code{sendfile()}
 @end itemize
@@ -29,16 +31,32 @@ from developers include:
 @item Streaming Earth observation data from NASA to the Internet
 @end itemize
 
+The remainder of this chapter will give a high-level overview of
+the library.
+
+@menu
+* libmicrohttpd-introduction-limitations::  Library limitations.
+* libmicrohttpd-introduction-threadmodes::  Thread modes and event loops.
+* libmicrohttpd-introduction-compiling::    Compiling libmicrohttpd.
+* libmicrohttpd-introduction-pointers::     Using MHD data.
+* libmicrohttpd-introduction-sigpipe::      SIGPIPE.
+* libmicrohttpd-introduction-w32::          Portability to W32.
+* libmicrohttpd-introduction-zos::          Portability to z/OS.
+@end menu
+
+
+@node libmicrohttpd-introduction-limitations
 @section Limitations
 
-The library is supposed to handle everything that it must handle
-(because the API would not allow clients to do this), such as basic
-connection management. However, some detailed interpretations of
-headers, such as range requests, are be left to the main application.
-In particular, if an application developer wants to support range
-requests, he needs to explicitly indicate support in responses and
-also explicitly parse the range header and generate a suitable
-response.
+MHD is supposed to handle everything that it must handle (because the
+API would not allow clients to do this), such as basic connection
+management. However, some detailed interpretations of headers, such as
+range requests, are be left to the main application.  In particular,
+if an application developer wants to support range requests, he needs
+to explicitly indicate support in responses and also explicitly parse
+the range header and generate a suitable response.
+@xref{libmicrohttpd2-requests} details with how applications can learn
+everything about incoming HTTP requests.
 
 MHD does understands headers that control connection management
 (specifically, @code{Connection: close} and @code{Expect: 100
@@ -47,13 +65,15 @@ continue} are understood and handled automatically).
 socket (or something that behaves like the real socket in the case of
 TLS) to the application (after sending the desired HTTP response
 header).
+@xref{libmicrohttpd2-upgrade} explains how to implement connection
+upgrades (for example, to implement WebSockets).
 
-MHD largely ignores the semantics of the different HTTP methods,
-so clients are left to handle those.  One exception is that MHD does
-understand @code{HEAD} and will only send the headers of the response
-and not the body, even if the client supplied a body.  (In fact,
-clients do need to construct a response with the correct length, even
-for @code{HEAD} request.)
+MHD largely leaves implementing the semantics of the different HTTP
+methods to the application.  One exception is that MHD does understand
+@code{HEAD} and will only send the headers of the response and not the
+body, even if the client supplied a body.  (In fact, applications do
+need to construct a response with the correct length, even for
+@code{HEAD} request.)
 
 MHD understands @code{POST} data and is able to decode certain
 formats (at the moment only @code{application/x-www-form-urlencoded}
@@ -61,14 +81,17 @@ and @code{multipart/form-data}) using the post processor 
API.  The
 data stream of a POST is also provided directly to the main
 application, so unsupported encodings could still be processed, just
 not conveniently by MHD.
+@xref{libmicrohttpd2-postprocessor} explains MHD functions for
+dealing with POST data in more detail.
 
 The @code{microhttp2.h} header file defines various constants used by
 the HTTP protocol.  This does not mean that MHD actually interprets
 all of these values.  The provided constants are exported as a
-convenience for users of the library.  MHD does not verify that
-transmitted HTTP headers are part of the standard specification; users
-of the library are free to define their own extensions of the HTTP
-standard and use those with MHD.
+convenience for users of the library.  MHD does not require that all
+transmitted HTTP headers are part of the standard specification;
+applications are free to define their own custom headers and use those
+with MHD.  Even setting standard headers incorrectly (for example, to test
+clients) is possible via the use of options to override sanity checks.
 
 All symbols defined in the public API start with @code{MHD_}.  All
 functions are guaranteed to be completely reentrant and thread-safe.
@@ -77,8 +100,11 @@ MHD checks for allocation failures and tries to recover 
gracefully
 specify resource limits on the overall number of connections, number
 of connections per IP address and memory used per connection to avoid
 resource exhaustion.
+@xref{libmicrohttpd2-options} explains the MHD API for configuring
+the various settings supported by the library.
 
 
+@node libmicrohttpd-introduction-threadmodes
 @section Thread modes and event loops
 @cindex poll
 @cindex epoll
@@ -100,6 +126,7 @@ is available on all platforms, epoll and poll may not be 
available on
 some platforms.  Note that it is possible to combine MHD using epoll
 with an external select-based event loop.
 
+@c FIXME: is this still the default?
 The default (if no other option is passed) is ``external select''.
 The highest performance can typically be obtained with a thread pool
 using @code{epoll}.  Apache Benchmark (ab) was used to compare the
@@ -136,20 +163,29 @@ In practice, you rarely need to worry about selecting the 
event
 loop style: MHD offers the "automatic" setting, which will pick
 the fastest mode available on your platform automatically.
 
+@xref{libmicrohttpd2-threadmodes} provides details on how to
+use MHD with the different thread modes.
 
+@node libmicrohttpd-introduction-compiling
 @section Compiling GNU libmicrohttpd
 @cindex compilation
 @cindex embedded systems
 @cindex portability
 
 MHD uses the standard GNU system where the usual build process
-involves running
+involves running:
+
 @verbatim
 $ ./configure
 $ make
 $ make install
 @end verbatim
 
+In terms of dependencies, MHD can optionally use OpenSSL or
+libgnutls for TLS support.  MHD has no hard dependencies
+other than libc, and tries to impose minimal requirements
+on the C standart library as well.
+
 MHD supports various options to be given to configure to tailor the
 binary to a specific situation.  Note that some of these options will
 remove portions of the MHD code that are required for
@@ -161,10 +197,12 @@ backend, otherwise unexpected incompatibilities can 
arise. In
 particular, the libtool versioning supported by MHD developers,
 assumes that you enable all of the optional features.
 
-Here is a list of MHD-specific options that can be given to configure
-(canonical configure options such as ``--prefix'' are also supported, for a
-full list of options run ``./configure --help''):
+Below is a list of MHD-specific options that can be given to
+configure:@footnote{Canonical configure options such
+as @code{--prefix} are also supported; for a
+full list of options run @code{./configure --help}}
 
+@c FIXME: check with current configure options!
 @table @code
 @item ``--disable-curl''
 disable running testcases using libcurl
@@ -206,12 +244,12 @@ specifies path to libgnutls installation
 
 To cross-compile MHD for Android, install the Android NDK and use:
 @verbatim
-./configure \
-  --target=arm-linux-androideabi \
-  --host=arm-linux-androideabi \
-  --disable-doc \
-  --disable-examples
-make
+$ ./configure \
+    --target=arm-linux-androideabi \
+    --host=arm-linux-androideabi \
+    --disable-doc \
+    --disable-examples
+$ make
 @end verbatim
 
 Similar build commands should work for cross-compilation to other platforms.
@@ -219,7 +257,11 @@ Note that you may have to first cross-compile the 
respective TLS library
 to get MHD with TLS support.
 
 
-@section Validity of pointers
+@node libmicrohttpd-introduction-pointers
+@section Applications using data provided by MHD
+
+@cindex lifetime
+@subsection Data lifetime
 
 MHD will give applications access to its internal data structures
 via pointers via arguments and return values from its API.  This
@@ -231,8 +273,9 @@ connection, request or response.  Thus, pointers associated 
with a
 session, connection, request or response are typically valid until the
 respective session, connection, request or response are completed.
 This is in particular true for all values obtained via the
-introspection APIs.
-@c FIXME: link to introspection chapter!
+introspection API.
+@xref{libmicrohttpd2-introspection,introspection APIs} has more
+details on the introspection API.
 
 Otherwise, values can generally only be assumed to be valid during the
 callback where MHD provided a value to the application. Finally,
@@ -240,30 +283,60 @@ unless stated otherwise, the application does not need to 
guarantee
 that values it passes into MHD APIs remain valid after the call to an
 MHD API returns.
 
+@cindex string
+@subsection Strings
+
+MHD will frequently make strings available to applications.
+In this case, MHD will return a @code{struct MHD_String} or
+a @code{struct MHD_StringNullable}.
 
+@deftp {C Struct} MHD_String len cstr
+Represents a string. The pointer is never NULL.
+@table @code
+@item len
+Number of characters in @var{str}, not counting 0-termination.
+@item cstr
+0-terminated C-string. Guaranteed to not be NULL.
+@end table
+@end deftp
+
+@deftp {C Struct} MHD_StringNullable len cstr
+Represents a string that could also be NULL.
+@table @code
+@item len
+Number of characters in @var{str}, not counting 0-termination.
+@item cstr
+0-terminated C-string. Could be NULL in some cases.
+@end table
+@end deftp
+
+
+@node libmicrohttpd-introduction-sigpipe
 @section SIGPIPE
 @cindex signals
+
 MHD does not install a signal handler for SIGPIPE.  On platforms where
 this is possible (such as GNU/Linux), it disables SIGPIPE for its I/O
-operations (by passing MSG_NOSIGNAL or similar).  On other platforms,
-SIGPIPE signals may be generated from network operations by MHD and
-will cause the process to die unless the developer explicitly installs
-a signal handler for SIGPIPE.
+operations (by passing @code{MSG_NOSIGNAL} or similar flags).  On
+platforms where this is not possible, SIGPIPE signals may be generated
+from network operations by MHD. This will cause the process to die
+unless the application explicitly installs a signal handler for SIGPIPE.
 
-Hence portable code using MHD must install a SIGPIPE handler or
-explicitly block the SIGPIPE signal.  MHD does not do so in order to
+Hence portable code using MHD @strong{must} install a SIGPIPE handler
+@emph{or} explicitly block the SIGPIPE signal.  MHD does not do so to
 avoid messing with other parts of the application that may need to
 handle SIGPIPE in a particular way.  You can make your application
-handle SIGPIPE by calling the following function in @code{main}:
+handle SIGPIPE by calling the following function in @code{main()}:
 
 @verbatim
 static void
 catcher (int sig)
 {
+  /* Ignore the signal */
 }
 
 static void
-ignore_sigpipe ()
+ignore_sigpipe (void)
 {
   struct sigaction oldsig;
   struct sigaction sig;
diff --git a/doc/manual/introspection.inc b/doc/manual/introspection.inc
index 17661d0..98a4b62 100644
--- a/doc/manual/introspection.inc
+++ b/doc/manual/introspection.inc
@@ -257,5 +257,3 @@ zero for no timeout.
 
 @end table
 @end deftp
-
-
diff --git a/doc/manual/structs.inc b/doc/manual/structs.inc
index 516c28f..b5e7a51 100644
--- a/doc/manual/structs.inc
+++ b/doc/manual/structs.inc
@@ -1,7 +1,4 @@
 
-@deftp {C Struct} MHD_Daemon
-Handle for the daemon (listening on a socket for HTTP clients).
-@end deftp
 
 @deftp {C Struct} MHD_Connection
 Connection to an HTTP client. Since HTTP2, multiple
@@ -17,7 +14,7 @@ over the same session.
 @end deftp
 
 @deftp {C Struct} MHD_Request
-Handle for an HTTP request.  
+Handle for an HTTP request.
 MHD will only show one request per session
 to the application at any given time.
 @end deftp
@@ -69,17 +66,6 @@ Represents information from a basic authorization
 client header. Includes the username and password.
 @end deftp
 
-@deftp {C Struct} MHD_String
-Represents a string. The pointer is never NULL.
-The character array is 0-terminated and its length
-(excluding 0-termination) is also given explicitly.
-@end deftp
-
-@deftp {C Struct} MHD_StringNullable
-Represents a string that could also be NULL.
-The character array is 0-terminated and its length
-(excluding 0-termination) is also given explicitly.
-@end deftp
 
 @deftp {C Struct} MHD_NameAndValueCStr
 Represents key-value pair, consisting of a
@@ -149,6 +135,3 @@ Information about an MHD request that will not change.
 @deftp {C Union} MHD_RequestInfoDynamicData
 Information about an MHD request that may change.
 @end deftp
-
-
-

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.