19.0.0 released Nov 08, 2023
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.
See also
Running application
application-setup  
CGI  
command-line  
containerize-application  
FastCGI  
plain-C-FCGI    
See all
documentation


You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a dofollow link back to this page - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind. Icons from table-icons.io copyright Paweł Kuna, licensed under MIT license.