This is libmicrohttpd.info, produced by makeinfo version 6.5 from
libmicrohttpd.texi.
This manual is for GNU libmicrohttpd (version 0.9.59, 9 December 2017),
a library for embedding an HTTP(S) server into C applications.
Copyright © 2007–2017 Christian Grothoff
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Software libraries
START-INFO-DIR-ENTRY
* libmicrohttpd: (libmicrohttpd). Embedded HTTP server library.
END-INFO-DIR-ENTRY
File: libmicrohttpd.info, Node: Top, Next: microhttpd-intro, Up: (dir)
The GNU libmicrohttpd Library
*****************************
This manual is for GNU libmicrohttpd (version 0.9.59, 9 December 2017),
a library for embedding an HTTP(S) server into C applications.
Copyright © 2007–2017 Christian Grothoff
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
* Menu:
* microhttpd-intro:: Introduction.
* microhttpd-const:: Constants.
* microhttpd-struct:: Structures type definition.
* microhttpd-cb:: Callback functions definition.
* microhttpd-init:: Starting and stopping the server.
* microhttpd-inspect:: Implementing external ‘select’.
* microhttpd-requests:: Handling requests.
* microhttpd-responses:: Building responses to requests.
* microhttpd-flow:: Flow control.
* microhttpd-dauth:: Utilizing Authentication.
* microhttpd-post:: Adding a ‘POST’ processor.
* microhttpd-info:: Obtaining and modifying status information.
* microhttpd-util:: Utilities.
Appendices
* GNU-LGPL:: The GNU Lesser General Public License says how you
can copy and share almost all of ‘libmicrohttpd’.
* GNU GPL with eCos Extension:: The GNU General Public License with eCos extension says how you
can copy and share some parts of ‘libmicrohttpd’.
* GNU-FDL:: The GNU Free Documentation License says how you
can copy and share the documentation of ‘libmicrohttpd’.
Indices
* Concept Index:: Index of concepts and programs.
* Function and Data Index:: Index of functions, variables and data types.
* Type Index:: Index of data types.
File: libmicrohttpd.info, Node: microhttpd-intro, Next: microhttpd-const, Prev: Top, Up: Top
1 Introduction
**************
All symbols defined in the public API start with ‘MHD_’. MHD is a small
HTTP daemon library. As such, it does not have any API for logging
errors (you can only enable or disable logging to stderr). Also, it may
not support all of the HTTP features directly, where applicable,
portions of HTTP may have to be handled by clients of the library.
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, detailed interpretations of headers,
such as range requests, are 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 response (for example, using the
‘MHD_create_response_from_fd_at_offset’ call to serve ranges from a
file). MHD does understands headers that control connection management
(specifically, ‘Connection: close’ and ‘Expect: 100 continue’ are
understood and handled automatically). ‘Connection: upgrade’ is
supported by passing control over the socket (or something that behaves
like the real socket in the case of TLS) to the application (after
sending the desired HTTP response header).
MHD largely ignores the semantics of the different HTTP methods, so
clients are left to handle those. One exception is that MHD does
understand ‘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 ‘HEAD’
request.)
MHD understands ‘POST’ data and is able to decode certain formats (at
the moment only ‘application/x-www-form-urlencoded’ and
‘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.
The 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.
All functions are guaranteed to be completely reentrant and
thread-safe. MHD checks for allocation failures and tries to recover
gracefully (for example, by closing the connection). Additionally,
clients can specify resource limits on the overall number of
connections, number of connections per IP address and memory used per
connection to avoid resource exhaustion.
1.1 Scope
=========
MHD is currently used in a wide range of implementations. Examples
based on reports we’ve received from developers include:
• Embedded HTTP server on a cortex M3 (128 KB code space)
• Large-scale multimedia server (reportedly serving at the simulator
limit of 7.5 GB/s)
• Administrative console (via HTTP/HTTPS) for network appliances
1.2 Thread modes and event loops
================================
MHD supports four basic thread modes and up to three event loop styles.
The four basic thread modes are external sockets polling (MHD creates
no threads, event loop is fully managed by the application), internal
polling (MHD creates one thread for all connections), polling in thread
pool (MHD creates a thread pool which is used to process all
connections) and thread-per-connection (MHD creates one thread for
listen sockets and then one thread per accepted connection).
These thread modes are then combined with the evet loop styles
(polling function type). MHD support select, poll and epoll. select 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.
The default (if no other option is passed) is “external select”. The
highest performance can typically be obtained with a thread pool using
‘epoll’. Apache Benchmark (ab) was used to compare the performance of
‘select’ and ‘epoll’ when using a thread pool and a large number of
connections. *note Figure 1.1: fig:performance. shows the resulting
plot from the ‘benchmark.c’ example, which measures the latency between
an incoming request and the completion of the transmission of the
response. In this setting, the ‘epoll’ thread pool with four threads
was able to handle more than 45,000 connections per second on loopback
(with Apache Benchmark running three processes on the same machine).
[image src="libmicrohttpd_performance_data.png" alt="Data"