### Configure option: --with-gnutls=PATH

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Specifies the path to the libgnutls installation.

```text
--with-gnutls=PATH
```

--------------------------------

### Build GNU libmicrohttpd with configure, make, and make install

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Standard build process for MHD. Run these commands in the source directory to configure, compile, and install the library. The configure step accepts options to tailor the build, but disabling features can break binary compatibility.

```shell
$ ./configure
$ make
$ make install

```

--------------------------------

### Configure option: --with-gcrypt=PATH

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Specifies the path to the libgcrypt installation.

```text
--with-gcrypt=PATH
```

--------------------------------

### MHD_start_daemon

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Starts a webserver on the given port. Returns NULL on error, handle to daemon on success.

```APIDOC
## MHD_start_daemon

### Description
Start a webserver on the given port. Returns NULL on error, handle to daemon on success.

### Function Signature
`struct MHD_Daemon *MHD_start_daemon(unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...)`

### Parameters
- **flags** (unsigned int) - Required - OR-ed combination of `MHD_FLAG` values.
- **port** (unsigned short) - Required - Port to bind to.
- **apc** (MHD_AcceptPolicyCallback) - Required - Callback to check which clients will be allowed to connect; can be NULL to accept connections from any IP.
- **apc_cls** (void*) - Required - Extra argument to apc.
- **dh** (MHD_AccessHandlerCallback) - Required - Default handler for all URIs.
- **dh_cls** (void*) - Required - Extra argument to dh.
- **...** - Optional - Additional arguments are a list of options (type-value pairs), terminated with `MHD_OPTION_END`. It is mandatory to use `MHD_OPTION_END` as last argument, even when there are no additional arguments.

### Return Value
Returns NULL on error, handle to daemon on success.
```

--------------------------------

### Example: Handling Digest Authentication Requests and Responses

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

A code example demonstrating how to use MHD_queue_auth_fail_response2 and related functions to handle digest authentication in a libmicrohttpd handler.

```APIDOC
## Example: Handling Digest Authentication Requests and Responses

### Description
This example shows a complete handler function that uses `MHD_digest_auth_get_username`, `MHD_digest_auth_check2`, and `MHD_queue_auth_fail_response2` to implement digest authentication.

### Code
```c
#define PAGE "<html><head><title>libmicrohttpd demo</title></head><body>Access granted</body></html>"
#define DENIED "<html><head><title>libmicrohttpd demo</title></head><body>Access denied</body></html>"
#define OPAQUE "11733b200778ce33060f31c9af70a870ba96ddd4"

static int
ahc_echo (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 **ptr)
{
  struct MHD_Response *response;
  char *username;
  const char *password = "testpass";
  const char *realm = "test@example.com";
  int ret;

  username = MHD_digest_auth_get_username (connection);
  if (username == NULL)
    {
      response = MHD_create_response_from_buffer(strlen (DENIED),
					         DENIED,
					         MHD_RESPMEM_PERSISTENT);
      ret = MHD_queue_auth_fail_response2 (connection,
                                           realm,
					   OPAQUE,
					   response,
					   MHD_NO,
                                           MHD_DIGEST_ALG_SHA256);
      MHD_destroy_response(response);
      return ret;
    }
  ret = MHD_digest_auth_check2 (connection,
                                realm,
			        username,
			        password,
			        300,
                                MHD_DIGEST_ALG_SHA256);
  free(username);
  if ( (ret == MHD_INVALID_NONCE) ||
       (ret == MHD_NO) )
    {
      response = MHD_create_response_from_buffer(strlen (DENIED),
					         DENIED,
					         MHD_RESPMEM_PERSISTENT);
      if (NULL == response)
	return MHD_NO;
      ret = MHD_queue_auth_fail_response2 (connection,
                                           realm,
					   OPAQUE,
					   response,
					   (ret == MHD_INVALID_NONCE) ? MHD_YES : MHD_NO,
                                           MHD_DIGEST_ALG_SHA256);
      MHD_destroy_response(response);
      return ret;
    }
  response = MHD_create_response_from_buffer (strlen(PAGE),
                                              PAGE,
 					      MHD_RESPMEM_PERSISTENT);
  ret = MHD_queue_response (connection,
                            MHD_HTTP_OK,
                            response);
  MHD_destroy_response(response);
  return ret;
}
```
```

--------------------------------

### Digest authentication request handler example

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Complete C example for handling digest authentication requests and responses. It uses MHD_digest_auth_get_username, MHD_digest_auth_check2, and MHD_queue_auth_fail_response2 with SHA256 algorithm. The example defines PAGE and DENIED HTML constants and an OPAQUE value.

```C
#define PAGE "<html><head><title>libmicrohttpd demo</title></head><body>Access granted</body></html>"
#define DENIED "<html><head><title>libmicrohttpd demo</title></head><body>Access denied</body></html>"
#define OPAQUE "11733b200778ce33060f31c9af70a870ba96ddd4"

static int
ahc_echo (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 **ptr)
{
  struct MHD_Response *response;
  char *username;
  const char *password = "testpass";
  const char *realm = "test@example.com";
  int ret;

  username = MHD_digest_auth_get_username (connection);
  if (username == NULL)
    {
      response = MHD_create_response_from_buffer(strlen (DENIED),
					         DENIED,
					         MHD_RESPMEM_PERSISTENT);
      ret = MHD_queue_auth_fail_response2 (connection,
                                           realm,
					   OPAQUE,
					   response,
					   MHD_NO,
                                           MHD_DIGEST_ALG_SHA256);
      MHD_destroy_response(response);
      return ret;
    }
  ret = MHD_digest_auth_check2 (connection,
                                realm,
			        username,
			        password,
			        300,
                                MHD_DIGEST_ALG_SHA256);
  free(username);
  if ( (ret == MHD_INVALID_NONCE) ||
       (ret == MHD_NO) )
    {
      response = MHD_create_response_from_buffer(strlen (DENIED),
					         DENIED,
					         MHD_RESPMEM_PERSISTENT);
      if (NULL == response)
	return MHD_NO;
      ret = MHD_queue_auth_fail_response2 (connection,
                                           realm,
					   OPAQUE,
					   response,
					   (ret == MHD_INVALID_NONCE) ? MHD_YES : MHD_NO,
                                           MHD_DIGEST_ALG_SHA256);
      MHD_destroy_response(response);
      return ret;
    }
  response = MHD_create_response_from_buffer (strlen(PAGE),
                                              PAGE,
 					      MHD_RESPMEM_PERSISTENT);
  ret = MHD_queue_response (connection,
                            MHD_HTTP_OK,
                            response);
  MHD_destroy_response(response);
  return ret;
}
```

--------------------------------

### Create response from a statically allocated string

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Example showing how to create a response from a static string using MHD_create_response_from_buffer with MHD_RESPMEM_PERSISTENT, then queue and destroy the response.

```c
const char * data = "<html><body><p>Error!</p></body></html>";

struct MHD_Connection * connection = ...;
struct MHD_Response *   response;

response = MHD_create_response_from_buffer (strlen(data), data,
                                            MHD_RESPMEM_PERSISTENT);
MHD_queue_response(connection, 404, response);
MHD_destroy_response(response);
```

--------------------------------

### C code: Install SIGPIPE handler

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Portable code using MHD must install a SIGPIPE handler or block the signal. This example defines a catcher function and an ignore_sigpipe function that installs a SIGPIPE handler with SA_INTERRUPT on SunOS or SA_RESTART otherwise, printing an error if sigaction fails.

```c
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));
}
```

--------------------------------

### MHD_create_response_for_upgrade

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Creates a response suitable for switching protocols (e.g., WebSockets). Requires the MHD_ALLOW_SUSPEND_RESUME flag to be set when starting the daemon. Returns MHD_YES on success.

```APIDOC
## MHD_create_response_for_upgrade

### Description
Create a response suitable for switching protocols. This is used for protocol upgrades such as WebSockets. The `Connection: Upgrade` header is set automatically, and an `Upgrade:` header must be set by the application.

### Function Signature
`enum MHD_Result MHD_create_response_for_upgrade(MHD_UpgradeHandler upgrade_handler, void *upgrade_handler_cls)`

### Parameters
- **upgrade_handler** (MHD_UpgradeHandler) - Required - Callback to handle the upgraded connection. Must not be `NULL`.
- **upgrade_handler_cls** (void *) - Required - Closure argument passed to the upgrade handler.

### Return Value
- `MHD_YES` on success.
- `MHD_NO` on error.

### Usage Notes
- Requires the `MHD_ALLOW_SUSPEND_RESUME` flag to be set when starting the daemon.
- The response must be queued with the `MHD_HTTP_SWITCHING_PROTOCOLS` status code.
- The `Connection: Upgrade` header is set automatically; an `Upgrade:` header must be set by the application.
```

--------------------------------

### MHD_OPTION_ARRAY example: initialize daemon with option array

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Shows how to use MHD_OPTION_ARRAY with a struct MHD_OptionItem array terminated by MHD_OPTION_END. The array sets connection limit and timeout, then passes the array to MHD_start_daemon. For options expecting a single pointer argument, the second member is ignored; for two-pointer options, the first must be cast to intptr_t.

```c
struct MHD_OptionItem ops[] = {
 { MHD_OPTION_CONNECTION_LIMIT, 100, NULL },
 { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL },
 { MHD_OPTION_END, 0, NULL }
};
d = MHD_start_daemon(0, 8080, NULL, NULL, dh, NULL,
                     MHD_OPTION_ARRAY, ops,
                     MHD_OPTION_END);

```

--------------------------------

### Configure option: --enable-coverage

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Sets flags for code-coverage analysis with gcc/gcov, resulting in slow, large binaries.

```text
--enable-coverage
```

--------------------------------

### Configure option: --disable-postprocessor

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Excludes the post processor API, resulting in binary incompatibility.

```text
--disable-postprocessor
```

--------------------------------

### Configure option: --disable-largefile

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Disables support for 64-bit files.

```text
--disable-largefile
```

--------------------------------

### MHD_basic_auth_get_username_password

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Gets the username and password from the basic authorization header sent by the client. Returns NULL if no username found.

```APIDOC
## MHD_basic_auth_get_username_password

### Description
Get the username and password from the basic authorization header sent by the client. Return `NULL` if no username could be found, a pointer to the username if found. If returned value is not `NULL`, the value must be `MHD_free()`’ed.

### Function Signature
```c
char *MHD_basic_auth_get_username_password(struct MHD_Connection *connection, char** password)
```

### Parameters
- **connection** (struct MHD_Connection *) - Required - The connection from which to extract credentials.
- **password** (char**) - Optional - Reference to a buffer to store the password. Can be NULL. If returned value is not NULL, the value must be `MHD_free()`’ed.

### Returns
- Pointer to username if found, otherwise NULL.
```

--------------------------------

### Convert source files to EBCDIC for z/OS

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Run these commands from the extracted archive to convert all source files to EBCDIC. Must run configure from the directory where the configure script is located, otherwise it will fail to find the contrib/xcc script.

```shell
iconv -f UTF-8 -t IBM-1047 contrib/ascebc > /tmp/ascebc.sh
chmod +x /tmp/ascebc.sh
for n in `find * -type f`
do
  /tmp/ascebc.sh $n
done
```

--------------------------------

### MHD_create_response_from_fd_at_offset

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Creates a response object from a file descriptor starting at a specified offset. The response can be extended with headers and used multiple times.

```APIDOC
## MHD_create_response_from_fd_at_offset

### Description
Creates a response object from a file descriptor starting at a specified offset. The response can be extended with headers and used multiple times.

### Function Signature
`struct MHD_Response *MHD_create_response_from_fd_at_offset(size_t size, int fd, off_t offset)`

### Parameters
- **size** (size_t) - Required - Size of the data portion of the response.
- **fd** (int) - Required - File descriptor referring to a file on disk with the data; will be closed when response is destroyed.
- **offset** (off_t) - Required - Offset in the file from which to start reading data. Note: ensure that `off_t` is 64-bit to avoid truncation; use `AC_SYS_LARGEFILE` or `_FILE_OFFSET_BITS 64`.

### Return Value
Returns `NULL` on error (i.e. invalid arguments, out of memory).
```

--------------------------------

### Configure option: --disable-dauth

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Excludes the authentication APIs, resulting in binary incompatibility.

```text
--disable-dauth
```

--------------------------------

### MHD_get_response_headers

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Gets all headers added to a response by invoking an iterator callback for each header. Returns the number of entries iterated over. The iterator can be NULL to just count headers.

```APIDOC
## MHD_get_response_headers

### Description
Get all of the headers added to a response. Invoke the iterator callback for each header in the response, using iterator_cls as first argument.

### Function Signature
`int MHD_get_response_headers(struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls)`

### Parameters
- **response** (struct MHD_Response *) - Required - The response whose headers are to be retrieved.
- **iterator** (MHD_KeyValueIterator) - Required - Callback invoked for each header. Can be `NULL` to just count headers.
- **iterator_cls** (void *) - Required - First argument passed to the iterator callback.

### Return Value
- Number of entries iterated over.

### Usage Notes
- The iterator should not modify its key and value arguments unless you know what you are doing.
```

--------------------------------

### MHD_get_fdset2

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Like MHD_get_fdset(), but allows manual specification of the FD_SETSIZE value used by the application. Returns MHD_YES on success, MHD_NO on invalid arguments or if the daemon was not started with the right options.

```APIDOC
## MHD_get_fdset2

### Description
Like `MHD_get_fdset()`, except that you can manually specify the value of FD_SETSIZE used by your application.

### Function Signature
`enum MHD_Result MHD_get_fdset2 (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd, unsigned int fd_setsize)`

### Parameters
- **daemon** (struct MHD_Daemon *) - Required - The daemon whose file descriptors are to be obtained.
- **read_fd_set** (fd_set *) - Required - Set to which read file descriptors are added.
- **write_fd_set** (fd_set *) - Required - Set to which write file descriptors are added.
- **except_fd_set** (fd_set *) - Required - Set to which exception file descriptors are added.
- **max_fd** (int *) - Required - Pointer to an integer that will be set to the highest file descriptor number. Must be initialized to zero before calling.
- **fd_setsize** (unsigned int) - Required - The value of FD_SETSIZE used by the application.

### Return Value
- **MHD_YES** - On success.
- **MHD_NO** - If arguments are invalid (e.g., NULL pointers) or if the daemon was not started with the right options for this call.
```

--------------------------------

### MHD_get_fdset

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Obtains the select() sets for the daemon, adding the daemon's socket and connection file descriptors to the provided sets. Returns MHD_YES on success, MHD_NO on invalid arguments or if the daemon was not started with the right options.

```APIDOC
## MHD_get_fdset

### Description
Obtain the `select()` sets for this daemon. The daemon’s socket is added to read_fd_set. The list of currently existent connections is scanned and their file descriptors added to the correct set.

### Function Signature
`enum MHD_Result 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)`

### Parameters
- **daemon** (struct MHD_Daemon *) - Required - The daemon whose file descriptors are to be obtained.
- **read_fd_set** (fd_set *) - Required - Set to which read file descriptors are added.
- **write_fd_set** (fd_set *) - Required - Set to which write file descriptors are added.
- **except_fd_set** (fd_set *) - Required - Set to which exception file descriptors are added.
- **max_fd** (int *) - Required - Pointer to an integer that will be set to the highest file descriptor number. Must be initialized to zero before calling.

### Return Value
- **MHD_YES** - On success.
- **MHD_NO** - If arguments are invalid (e.g., NULL pointers) or if the daemon was not started with the right options for this call.

### Notes
- This function should only be called when MHD is configured to use external select with `select()` or with `epoll()`. In the latter case, it will only add the single `epoll()` file descriptor used by MHD to the sets.
- When calling this function, FD_SETSIZE is assumed to be platform’s default. If you changed FD_SETSIZE for your application, you should use `MHD_get_fdset2()` instead.
```

--------------------------------

### Configure option: --disable-httpupgrade

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Disables building code for HTTP 'Upgrade', resulting in a smaller binary size and a binary incompatible library.

```text
--disable-httpupgrade
```

--------------------------------

### MHD_run_from_select

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Runs webserver operations given sets of ready socket handles. More efficient than MHD_run when using external select.

```APIDOC
## MHD_run_from_select

### Description
Run webserver operations given sets of ready socket handles. This method should be called by clients in combination with `MHD_get_fdset` if the client-controlled (external) select method is used. You can use this function instead of `MHD_run` if you called `select` on the result from `MHD_get_fdset`. File descriptors in the sets that are not controlled by MHD will be ignored. Calling this function instead of `MHD_run` is more efficient as MHD will not have to call `select` again to determine which operations are ready.

### Function Signature
`enum MHD_Result MHD_run_from_select(struct MHD_Daemon *daemon, const fd_set *read_fd_set, const fd_set *write_fd_set, const fd_set *except_fd_set)`

### Parameters
- **daemon** (struct MHD_Daemon*) - Required - Daemon to process connections of.
- **read_fd_set** (const fd_set*) - Required - Set of descriptors that must be ready for reading without blocking.
- **write_fd_set** (const fd_set*) - Required - Set of descriptors that must be ready for writing without blocking.
- **except_fd_set** (const fd_set*) - Optional - Ignored, can be NULL.

### Return Value
Returns `MHD_YES` on success, `MHD_NO` on serious internal errors.
```

--------------------------------

### Configure option: --disable-curl

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Disables running testcases using libcurl.

```text
--disable-curl
```

--------------------------------

### Configure option: --disable-https

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Disables HTTPS support even if GNUtls is found. Must be used if eCOS license is desired; the resulting binary falls under a GNU LGPL-only license.

```text
--disable-https
```

--------------------------------

### MHD_OPTION_ARRAY

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Initializes MHD using options from an array. This is commonly used for writing an FFI for MHD. The actual options are given in an array of 'struct MHD_OptionItem', so this option requires a single argument of type 'struct MHD_OptionItem'. The array must be terminated with an entry MHD_OPTION_END.

```APIDOC
## MHD_OPTION_ARRAY

### Description
Initializes MHD using options from an array. This is commonly used for writing an FFI for MHD. The actual options are given in an array of 'struct MHD_OptionItem', so this option requires a single argument of type 'struct MHD_OptionItem'. The array must be terminated with an entry MHD_OPTION_END.

### Parameters
- **options** (struct MHD_OptionItem) - Required - Array of options, terminated with MHD_OPTION_END.

### Request Example
```c
struct MHD_OptionItem ops[] = {
 { MHD_OPTION_CONNECTION_LIMIT, 100, NULL },
 { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL },
 { MHD_OPTION_END, 0, NULL }
};
d = MHD_start_daemon(0, 8080, NULL, NULL, dh, NULL,
                     MHD_OPTION_ARRAY, ops,
                     MHD_OPTION_END);
```

### Notes
For options that expect a single pointer argument, the second member of the struct MHD_OptionItem is ignored. For options that expect two pointer arguments, the first argument must be cast to intptr_t.
```

--------------------------------

### Configure option: --with-threads=posix,w32,none,auto

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Sets the threading library to use. With 'none', MHD only supports 'external' threading modes and performs no locking; use MHD_is_feature_supported(MHD_FEATURE_THREADS) to test. Default is 'auto'.

```text
--with-threads=posix,w32,none,auto
```

--------------------------------

### Configure option: --disable-epoll

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Excludes epoll support even if supported, minimally smaller binary size and good for portability testing.

```text
--disable-epoll
```

--------------------------------

### MHD_run

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Runs webserver operations without blocking unless in client callbacks. Should be used with MHD_get_fdset() for client-controlled select method.

```APIDOC
## MHD_run

### Description
Run webserver operations (without blocking unless in client callbacks). This method should be called by clients in combination with `MHD_get_fdset()` if the client-controlled `select`-method is used. This function will work for external `poll` and `select` mode. However, if using external `select` mode, you may want to instead use `MHD_run_from_select`, as it is more efficient.

### Function Signature
`enum MHD_Result MHD_run(struct MHD_Daemon *daemon)`

### Parameters
- **daemon** (struct MHD_Daemon*) - Required - Daemon to process connections of.

### Return Value
Returns `MHD_YES` on success, `MHD_NO` if this daemon was not started with the right options for this call.
```

--------------------------------

### Define _FILE_OFFSET_BITS for 64-bit off_t support

Source: https://www.gnu.org/software/libmicrohttpd/manual/libmicrohttpd.html

Required before including microhttpd.h when using MHD_create_response_from_fd_at_offset on GNU/Linux without autotools. Ensures off_t is 64-bit to avoid passing 32-bit garbage.

```c
#define _FILE_OFFSET_BITS 64
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <microhttpd.h>
```