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"