Synopsis

kcgi is an open source CGI and FastCGI library for C/C++ web applications. It is minimal, secure, and auditable; and fits within your BCHS software stack.

This repository consists of bleeding-edge code between versions: to keep up to date with the current stable release of kcgi, visit the kcgi website. The website also contains canonical installation, deployment, and usage documentation. This page describes using the bleeding-edge version of the system.

Example

Implementing a CGI or FastCGI application with kcgi is easy (for values of easy strictly greater than "knows C/C++"). Specify the pages recognised by the application and the known HTML form inputs. kcgi parses the request and can manage output.

#include <sys/types.h> /* size_t, ssize_t */
#include <stdarg.h> /* va_list */
#include <stddef.h> /* NULL */
#include <stdint.h> /* int64_t */
#include <kcgi.h>
 
int main(void) {
  struct kreq r;
  const char *page = "index";
  if (KCGI_OK != khttp_parse(&r, NULL, 0, &page, 1, 0))
	return 0;
  khttp_head(&r, kresps[KRESP_STATUS],
	"%s", khttps[KHTTP_200]);
  khttp_head(&r, kresps[KRESP_CONTENT_TYPE], 
	"%s", kmimetypes[KMIME_TEXT_PLAIN]);
  khttp_body(&r);
  khttp_puts(&r, "Hello, world!\n");
  khttp_free(&r);
  return 0;
}

For a fuller example reflecting the repository sources, see sample.c or, for C++, samplepp.cc.

Installation

To use the bleeding-edge version of kcgi (instead of from your system's packages or a stable version), the process it the similar as for source releases.

Begin by cloning or downloading. Then configure with ./configure, compile with make (GNU make, so it may be gmake on your system), then sudo make install (or using doas). To install in an alternative directory to /usr/local, set the PREFIX variable when you run configure. (See the configure script for details.)

./configure
make
doas make install

You can also change the default value in the GNUmakefile.

API Reference

For the repository version of kcgi, the locally-installed manpages are the canonical source of information. (The web-site reflects the latest release, which may be older than what you have.)

man kcgi
apropos kcgi

This assumes that kcgi has been installed in a path recognised by your manpage reader. If you're using an alternative installation path, you may need to edit /etc/man.conf or other configuration file appropriate to your system.

Tests

It's useful to run the installed regression tests on the bleeding edge sources. (Again, this uses GNU make, so it may be gmake on your system.)

make regress

The system contains a full regression suite and is also built to work with AFL. To run some of the bundled tests, use the binaries compiled into the afl directory. (Again, this uses GNU make, so it may be gmake on your system.)

make afl
cd afl
afl-fuzz -i in/urlencoded -o out -- ./afl-urlencoded

License

All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.