Next: , Previous: 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 — and HTTP methods are left to clients. The library does understand HEAD and will only send the headers of the response and not the body, even if the client supplied a body. The library also understands headers that control connection management (specifically, Connection: close and Expect: 100 continue are understood and handled automatically).

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:

1.2 Compiling GNU libmicrohttpd

MHD uses the standard GNU system where the usual build process involves running

$ ./configure
$ make
$ make install

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 binary-compatibility. They should only be used on embedded systems with tight resource constraints and no concerns about library versioning. Standard distributions including MHD are expected to always ship with all features enabled, otherwise unexpected incompatibilities can arise!

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”):

``--disable-curl''
disable running testcases using libcurl
``--disable-largefile''
disable support for 64-bit files
``--disable-messages''
disable logging of error messages (smaller binary size, not so much fun for debugging)
``--disable-https''
disable HTTPS support, even if GNUtls is found; this option must be used if eCOS license is desired as an option (in all cases the resulting binary falls under a GNU LGPL-only license)
``--disable-postprocessor''
do not include the post processor API (results in binary incompatibility)
``--disable-dauth''
do not include the authentication APIs (results in binary incompatibility)
``--enable-coverage''
set flags for analysis of code-coverage with gcc/gcov (results in slow, large binaries)
``--with-gcrypt=PATH''
specifies path to libgcrypt installation
``--with-gnutls=PATH''
specifies path to libgnutls installation

1.3 Including the microhttpd.h header

Ideally, before including "microhttpd.h" you should add the necessary includes to define the uint64_t, size_t, fd_set, socklen_t and struct sockaddr data types. Which specific headers are needed may depend on your platform and your build system might include some tests to provide you with the necessary conditional operations. For possible suggestions consult platform.h and configure.ac in the MHD distribution.

Once you have ensured that you manually (!) included the right headers for your platform before "microhttpd.h", you should also add a line with #define MHD_PLATFORM_H which will prevent the "microhttpd.h" header from trying (and, depending on your platform, failing) to include the right headers.

If you do not define MHD_PLATFORM_H, the "microhttpd.h" header will automatically include headers needed on GNU/Linux systems (possibly causing problems when porting to other platforms).

1.4 SIGPIPE

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). 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.

Hence portable code using MHD must install a SIGPIPE handler or explicitly block the SIGPIPE signal. MHD does not do so in order 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 main:

static void
catcher (int sig)
{
}

static void
ignore_sigpipe ()
{
  struct sigaction oldsig;
  struct sigaction sig;

  sig.sa_handler = &catcher;
  sigemptyset (&sig.sa_mask);
#ifdef SA_INTERRUPT
  sig.sa_flags = SA_INTERRUPT;  /* SunOS */
#else
  sig.sa_flags = SA_RESTART;
#endif
  if (0 != sigaction (SIGPIPE, &sig, &oldsig))
    fprintf (stderr,
             "Failed to install SIGPIPE handler: %s\n", strerror (errno));
}

1.5 MHD_UNSIGNED_LONG_LONG

Some platforms do not support long long. Hence MHD defines a macro MHD_UNSIGNED LONG_LONG which will default to unsigned long long. For standard desktop operating systems, this is all you need to know.

However, if your platform does not support unsigned long long, you should change "platform.h" to define MHD_LONG_LONG and MHD_UNSIGNED_LONG_LONG to an appropriate alternative type and also define MHD_LONG_LONG_PRINTF and MHD_UNSIGNED_LONG_LONG_PRINTF to the corresponding format string for printing such a data type. Note that the “signed” versions are deprecated. Also, for historical reasons, MHD_LONG_LONG_PRINTF is without the percent sign, whereas MHD_UNSIGNED_LONG_LONG_PRINTF is with the percent sign. Newly written code should only use the unsigned versions. However, you need to define both in "platform.h" if you need to change the definition for the specific platform.