Plain C FCGI

Purpose: Building FastCGI programs in C.

See below

Plain C programs (linked with fcgi, the FastCGI library) can run as server applications with vf FastCGI program manager, which is used to start, stop and manage such applications.

Your program should include "fcgi_stdio.h" include file, and handle incoming requests in a loop by accepting them via FCGI_Accept() function, which is provided by fcgi library. Also, your program must handle SIGTERM signal properly and terminate when signalled without disruption to request processing.

An example of a simple program that fulfills these requirements is shown here.

Flags "busy" and "end_program" are used to handle a termination signal. "busy" is set to 1 while in the processing request loop; if termination signal happens then, "end_program" will be set to 1 so the program can exit once the request is processed. If termination signal happens during any other time (most likely while waiting for request in FCGI_Accept()), the program will exit right away.

Examples

The code below is a "Hello World" example that runs as a server - save it to file plain_fcgi.c:

#include "fcgi_stdio.h"
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <signal.h>

static int busy = 0; // busy processing request?
static int end_program = 0; // flag to terminate process

// Handle termination signal by setting flag
void signal_handler(int sig) {
    if (sig == SIGTERM) {
        // if not busy, exit now. If busy, exit when the main loop ends
        if (busy == 0) exit(0);
        end_program = 1;
        return;
    }
}

// Main FCGI process
void main(void) {
    // Set termination signal handler
    struct sigaction psa;
    memset (&psa, 0, sizeof (psa));
    psa.sa_handler = signal_handler;
    sigaction(SIGTERM, &psa, NULL);


    // main FCGI request-processing loop, simply display Hello world page each time
    while (FCGI_Accept() >= 0)   {
        busy = 1; // program busy now

        printf("Content-type: text/html\r\n"
           "\r\n"
           "<title>Hello World!</title>"
           "<h1>Hello there!</h1>");

        busy = 0; // program no longer busy
        // exit graceful at the end of request processing loop
        if (end_program) exit(0);
    }
 }

Initialize application

Before vf can run your program as a server, your application must be initialized - this is done only once:

sudo vf -i -u $USER plain_fcgi

Compile application

To compile and link this C program on any distro other than OpenSUSE:

gcc -o /var/lib/vv/bld/plain_fcgi/plain_fcgi plain_fcgi.c -lfcgi

For OpenSUSE, use the following:

gcc -o /var/lib/vv/bld/plain_fcgi/plain_fcgi plain_fcgi.c -lfcgi -I /usr/include/fastcgi

Start application

To start your server application with 2 parallel workers:

vf -w 2 plain_fcgi

Or if you are using TCP to connect to your application, in this case TCP port 2300:

vf -w 2 -p 2300 plain_fcgi

Configure web server (reverse proxy)

To setup a web server to use your application, your must set it up - see application_setup. Make sure to replace <app name> with the actual application name, in this case "plain_fcgi".

Run application

To see your application running, enter this in your browser, assuming your web server is accessible as localhost, i.e. 127.0.0.1 (otherwise replace 127.0.0.1 with your server hostname):

http://127.0.0.1/plain_fcgi

If you wish to stop the FastCGI server and your application:

vf -m quit plain_fcgi

Whenever you recompile your C program, vf will automatically reload it. For more information on all the options available, see vf.