DragonFly On-Line Manual Pages
KCGI(3) DragonFly Library Functions Manual KCGI(3)
NAME
kcgi - minimal CGI and FastCGI library in C
LIBRARY
library "libkcgi"
DESCRIPTION
The kcgi library handles the CGI or FastCGI environment for C web
applications. Interfacing applications generally work as follows:
1. Call khttp_parse(3) as early as possible. This will parse and
validate input fields and cookies with the kvalid_string(3) family
of functions or those provided by the calling application. It will
do so in memory, so enormous requests (e.g., files) will occur
entirely in memory! It also sets up the HTTP environment:
compression, paths, MIME types, and so on.
2. Process input fields by examining the struct kpair elements.
3. Emit HTTP headers with khttp_head(3), followed by khttp_body(3) to
begin the HTTP body.
4. Emit HTTP body output using the khttp_template(3) templating system,
the khttp_write(3) family for general HTTP content, and/or an
external library such as kcgihtml(3). Do not use printf(3) or other
functions to append to standard output: kcgi will automatically
compress output if requested by the client, and overriding the
output stream will circumvent this behaviour and might mix
compressed and uncompressed data.
5. Call khttp_free(3) to clean up.
It can also accept FastCGI connections in a manner similar to the above,
except that the parse routine is run within a loop.
1. Call khttp_fcgi_init(3) as early as possible.
2. Iterate over khttp_fcgi_parse(3) for as many connections as desired,
performing any processing on the created request. Each parse must
be matched with khttp_free(3).
3. Call khttp_fcgi_free(3) when all processing is complete.
To compile applications with kcgi, make sure kcgi.h is in the header path
and libkcgi.a in the library path, then link with -lkcgi and -lz (unless
compression has been disabled at compile-time). For example,
% cc -I/usr/local/include -c -o sample.o sample.c
% cc -L/usr/local/lib -o sample sample.o -lkcgi -lz
If the library will be statically linked (e.g., for running within a
chroot(2)), and assuming you'll use the kcgihtml(3) library, link as
follows:
% cc -o sample -static sample.o -lkcgihtml -lkcgi -lz
EXAMPLES
The following simple example assumes that kcgi.h is in the compiler's
include path. It does nothing but emit "Hello, world!" to the output.
#include <stdint.h>
#include <stdlib.h>
#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(EXIT_FAILURE);
khttp_head(&r, kresps[KRESP_STATUS],
"%s", khttps[KHTTP_200]);
khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
"%s", kmimetypes[r.mime]);
khttp_body(&r);
khttp_puts(&r, "Hello, world!");
khttp_free(&r);
return(EXIT_SUCCESS);
}
This can be extended to work with the FastCGI interface by allowing the
request parser to operate within a loop.
#include <stdint.h>
#include <stdlib.h>
#include <kcgi.h>
int main(void) {
struct kreq r;
struct kfcgi *fcgi;
const char *page = "index";
if (KCGI_OK != khttp_fcgi_init(&fcgi, NULL, 0, &page, 1, 0))
return(EXIT_FAILURE);
while (KCGI_OK == khttp_fcgi_parse(fcgi, &req)) {
khttp_head(&r, kresps[KRESP_STATUS],
"%s", khttps[KHTTP_200]);
khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
"%s", kmimetypes[r.mime]);
khttp_body(&r);
khttp_puts(&r, "Hello, world!");
khttp_free(&r);
}
khttp_fcgi_free(fcgi);
return(EXIT_SUCCESS);
}
In a more complicated example, kcgi accepts a single parameter "string"
to validate and display. This might be provided as part of an HTML form
or directly as part of the URL query string.
#include <stdint.h>
#include <stdlib.h>
#include <kcgi.h>
int main(void) {
struct kreq r;
struct kpair *p;
const char *page = "index";
struct kvalid key = { kvalid_stringne, "string" };
if (KCGI_OK != khttp_parse(&r, &key, 1, &page, 1, 0))
return(EXIT_FAILURE);
khttp_head(&r, kresps[KRESP_STATUS],
"%s", khttps[KHTTP_200]);
khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
"%s", kmimetypes[r.mime]);
khttp_body(&r);
khttp_puts(&r, "Result: ");
if ((p = r.fieldmap[0]))
khttp_puts(&r, p->parsed.s);
else if (r.fieldnmap[0])
khttp_puts(&r, "bad parse");
else
khttp_puts(&r, "no value");
khttp_free(&r);
return(EXIT_SUCCESS);
}
Applications will usually specify an array of key-value pairs to
validate; or in the event of web services, a default validator (empty
string) for the full HTTP message body.
SEE ALSO
kcgi(3), kcgihtml(3), kcgijson(3), kcgiregress(3), kcgixml(3),
khttp_body(3), khttp_fcgi_free(3), khttp_fcgi_init(3),
khttp_fcgi_parse(3), khttp_fcgi_test(3), khttp_free(3), khttp_head(3),
khttp_parse(3), khttp_template(3), khttp_write(3),
khttpbasic_validate(3), khttpdigest_validate(3), kmalloc(3),
kutil_urlencode(3), kvalid_string(3), kfcgi(8)
STANDARDS
Many standards are involved in the kcgi library, most significantly being
draft RFC 3875, "The Common Gateway Interface (CGI) Version 1.1", and the
"FastCGI Specification", version 1.0, published 29 April 1996.
* The "Authentication" header is parsed for digest or basic tokens as
defined by RFC 2617, "HTTP Authentication: Basic and Digest Access
Authentication".
* The partial multipart form data support is defined by RFC 2388,
"Returning Values from Forms: multipart/form-data", which is further
defined by RFCs 2045 and 2046, "Multipurpose Internet Mail
Extensions".
* MIME type names are registered with IANA.
* URLs are formatted according to RFC 1630, "Universal Resource
Identifiers in WWW".
* HTTP response headers are standardised in RFC 2616, "HTTP/1.1" and
further in RFC 4229, "HTTP Header Field Registrations".
* Permanent URI schemes are registered with IANA.
Additional HTTP methods are defined by RFC 4918, "HTTP Extensions for Web
Distributed Authoring and Versioning"; and RFC 4791 , "Calendaring
Extensions to WebDAV".
AUTHORS
The kcgi library was written by Kristaps Dzonsons <kristaps@bsd.lv>.
DragonFly 6.5-DEVELOPMENT January 12, 2016 DragonFly 6.5-DEVELOPMENT