DragonFly On-Line Manual Pages

KHTTP_FCGI_INIT(3)    DragonFly 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
     applications.  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
     application must use SIGKILL inside of the FastCGI-specified SIGTERM.

RETURN VALUES
     khttp_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 ALSO
     kcgi(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>.

DragonFly 6.5-DEVELOPMENT       January 4, 2016      DragonFly 6.5-DEVELOPMENT