KHTTP_FCGI_INIT(3) Library Functions Manual KHTTP_FCGI_INIT(3)

khttp_fcgi_init, khttp_fcgi_initxinitialise a FastCGI context for kcgi

library “libkcgi”

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>

enum kcgi_err
khttp_fcgi_init(struct kfcgi **fcgi, const struct kvalid *keys, size_t keysz, const char *const *pages, size_t pagesz, size_t defpage);

enum kcgi_err
khttp_fcgi_initx(struct kreq **fcgi, const char *const *mimes, size_t mimemax, const struct kvalid *keys, size_t keysz, const struct kmimemap *mimemap, size_t defmime, const char *const *pages, size_t pagesz, size_t defpage, void *arg, void (*argfree)(void *arg), unsigned int debugging, const struct kopts *opts);

The () and () functions initialise a FastCGI context for kcgi(3). These functions will only work if invoked as FastCGI servers, for example, kfcgi(8). They should be called as early as possible in the life-span of a FastCGI application, preferably directly after initialisation.

The collective arguments are defined in khttp_parse(3). : all pointers are passed by reference and used in later invocations of khttp_fcgi_parse(3).

The first form, (), is for applications using the system-recognised MIME types. This should work well enough for most applications. It is equivalent to invoking the second form, (), as follows:

khttp_fcgi_initx(fcgi, kmimetypes, KMIME__MAX,
  keys, keysz, ksuffixmap, KMIME_TEXT_HTML,
  pages, pagesz, defpage, NULL, NULL, 0, NULL);

After invocation with a return value of KCGI_OK, the fcgi pointer is filled in (and must be later be freed with khttp_fcgi_free(3)) and the khttp_fcgi_parse(3) and khttp_fcgi_parsex(3) functions may be invoked.

: in accordance with the FastCGI specification, () and () will install signal handlers for SIGTERM. These should not be changed by the calling application, but are not prohibited from doing so. The consequences are that a server wishing to halt the application must use SIGKILL instead of the FastCGI-specified SIGTERM and suffer the consequences of not properly exiting the parse loop.

khttp_fcgi_init() and khttp_fcgi_initx() return an error code:

Success (not an error).
Memory failure. This can occur in many places: spawning a child, allocating memory, creating sockets, etc.
Could not allocate file descriptors.
Could not spawn a child.
Opaque operating system error.
Hangup: the function was not invoked in a FastCGI context.

On failure, the calling application should terminate as soon as possible.

kcgi(3), khttp_fcgi_free(3), khttp_fcgi_parse(3), khttp_parse(3)

The khttp_fcgi_init() and khttp_fcgi_initx() functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

September 15, 2024 OpenBSD 7.5