KHTTP_FCGI_INIT(3) BSD Library Functions Manual KHTTP_FCGI_INIT(3)NAME
khttp_fcgi_init, khttp_fcgi_initx — initialise a FastCGI context for kcgi
LIBRARY
library “libkcgi”
SYNOPSIS
#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);
DESCRIPTION
The khttp_fcgi_init and khttp_fcgi_initx 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, preferrably
directly after initialisation.
The collective arguments are defined in khttp_parse(3). Function
arguments are not copied: all pointers are passed by reference and used
in later invocations of khttp_fcgi_parse(3).
The first form, khttp_fgci_init, is for applications using the system-
recognised MIME types. This should work well enough for most applica‐
tions. It is equivalent to invoking the second form, khttp_fcgi_initx,
as follows:
khttp_fcgi_initx(fcgi, kmimetypes, KMIME__MAX,
keys, keysz, ksuffixmap, KMIME_TEXT_HTML,
pages, pagesz, defpage, NULL, NULL, 0);
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.
Note: in accordance with the FastCGI specification, khttp_fcgi_init and
khttp_fcgi_initx 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 appli‐
cation must use SIGKILL inside of the FastCGI-specified SIGTERM.
RETURN VALUESkhttp_fcgi_init and khttp_fcgi_initx return an error code:
KCGI_OK
Success (not an error).
KCGI_ENOMEM
Memory failure. This can occur in many places: spawning a child,
allocating memory, creating sockets, etc.
KCGI_ENFILE
Could not allocate file descriptors.
KCGI_EAGAIN
Could not spawn a child.
KCGI_SYSTEM
Opaque operating system error.
KCGI_HUP
Hangup: the function was not invoked in a FastCGI context.
On failure, the calling application should terminate as soon as possible.
SEE ALSOkcgi(3), khttp_fcgi_free(3), khttp_fcgi_parse(3), khttp_parse(3)AUTHORS
The khttp_fcgi_init and khttp_fcgi_initx functions were written by
Kristaps Dzonsons ⟨kristaps@bsd.lv⟩.
BSD April 29, 2024 BSD
