-<html>
-
-<head>
-<title>FastCGI Developer's Kit</title>
-</head>
-
-<body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011" vlink="#555555">
-<a href="/fastcgi/words">
-
-<p align="center"><img border="0" src="/kit/images/fcgi-hd.gif" alt="[[FastCGI]]"></a> <br
-clear="all">
-</p>
-
-<h3 align="center">FastCGI Developer's Kit</h3>
-<!--Copyright (c) 1996 Open Market, Inc. -->
-<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
-<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
-
-<p align="center">Mark R. Brown<br>
-Open Market, Inc.<br>
-</p>
-
-<p align="center">Document Version: 1.08<br>
-11 June 1996<br>
-</p>
-
-<h5 align="center">Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA
-02142 U.S.A.<br>
-Tel: 617-621-9500 Fax: 617-621-1703 URL: <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
-$Id: fcgi-devel-kit.htm,v 1.2 1999/02/06 06:15:11 roberts Exp $ <br>
-</h5>
-
-<hr>
-
-<ul type="square">
- <li><a HREF="#S1">1. Introduction</a> </li>
- <li><a HREF="#S2">2. Getting started</a> </li>
- <li><a HREF="#S3">3. Writing applications</a> <ul type="square">
- <li><a HREF="#S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> </li>
- <li><a HREF="#S3.2">3.2 Using the <tt>fcgiapp</tt> library</a> </li>
- <li><a HREF="#S3.3">3.3 Using Perl and Tcl</a> </li>
- <li><a HREF="#S3.4">3.4 Using Java</a> </li>
- </ul>
- </li>
- <li><a HREF="#S4">4. Running applications</a> <ul type="square">
- <li><a HREF="#S4.1">4.1 Using a Web server that supports FastCGI</a> </li>
- <li><a HREF="#S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a> </li>
- </ul>
- </li>
- <li><a HREF="#S5">5. Known problems</a> </li>
- <li><a HREF="#S6">6. Getting support</a> </li>
-</ul>
-
-<hr>
-
-<h3><a NAME="S1">1. Introduction</a></h3>
-
-<p>FastCGI is an open extension to CGI that provides high performance for all Internet
-applications without the penalties of Web server APIs.</p>
-
-<p>FastCGI is designed to be layered on top of existing Web server APIs. For instance, the
-<tt>mod_fastcgi</tt> Apache module adds FastCGI support to the Apache server. FastCGI can
-also be used, with reduced functionality and reduced performance, on any Web server that
-supports CGI.</p>
-
-<p>This FastCGI Developer's Kit is designed to make developing FastCGI applications easy.
-The kit currently supports FastCGI applications written in C/C++, Perl, Tcl, and Java.</p>
-
-<p>This document:
-
-<ul type="square">
- <li>Describes how to configure and build the kit for your development platform. </li>
- <li>Tells how to write applications using the libraries in the kit. </li>
- <li>Tells how to run applications using Web servers that support FastCGI or using any Web
- server and <tt>cgi-fcgi</tt>. </li>
-</ul>
-
-<p>The kit includes a <a href="fastcgi-whitepaper/fastcgi.htm">technical white paper</a>, <tt>doc/fastcgi-whitepaper/fastcgi.htm</tt>.
-You should read at least the first three sections of the technical white paper before
-starting to write FastCGI applications. The <a href="fcgi-perf.htm">performance paper</a>
-will help you understand how application design affects performance with FastCGI.</p>
-
-<p>The <a href="fcgi-spec.html">FastCGI Specification</a>, <tt>doc/fcgi-spec.html</tt>,
-defines the interface between a FastCGI application and a Web server that supports
-FastCGI. The software in the kit implements the specification. You don't need to read the
-specification in order to write applications.</p>
-
-<p>Additional information is provided in the <a
-href="http://www.fastcgi.com/words/FAQ.htm">FAQ</a> document, which contains frequently
-asked questions about application development using FastCGI, as well as some general
-information.</p>
-
-<p>Experience with CGI programming will be extremely valuable in writing FastCGI
-applications. If you don't have enough experience with CGI programming, you should read
-one of the popular books on the topic or study the <a
-href="http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</a>. For a more formal treatment of
-CGI/1.1 see the <a
-href="http://ds.internic.net/internet-drafts/draft-robinson-www-interface-01.txt">Internet
-Draft CGI 1.1 Specification</a>.</p>
-
-<h3><a NAME="S2">2. Getting started</a></h3>
-
-<p>The kit is a compressed tar (tar.Z) file, distributed via the <a
-href="http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a> Web page. Unpacking the
-tar file creates a new directory <tt>fcgi-devel-kit</tt>.</p>
-
-<p>Open the kit's index page, <tt>fcgi-devel-kit/index.html</tt>, using the "Open
-File" command in your Web browser. The index page gives you an overview of the kit
-structure and helps you navigate the kit. The index page also contains links that run some
-example applications, but the applications won't work when index.html is opened using the
-"Open File" command because they aren't aren't being accessed through a Web
-server.</p>
-
-<p>In order to use the kit in earnest you'll need a Web server that you control, a Web
-server running with your user ID. The Web server will be starting FastCGI applications
-that you will need to debug; this will be a lot more convenient for you if these processes
-run with your user ID. It is best to have a Web server that supports FastCGI. <a
-href="#S4">Section 4</a> discusses Web server issues.</p>
-
-<p>If you can, keep the kit on a file system accessible from your personal workstation, do
-your builds on your workstation, and run your Web server on your workstation. If that's
-not possible, arrange a configuration such that the kit is accessible from the machine
-that's going to run your Web server, and build the kit and your applications on a machine
-that's configured exactly the same way (same processor architecture, operating system,
-etc.) as the machine that's going to run your Web server.</p>
-
-<p>To build the kit you execute this sequence of commands in the <tt>fcgi-devel-kit</tt>
-directory:</p>
-
-<pre>
- % ./configure
- % make
-</pre>
-
-<p>We've built and exercised the kit on these platforms (listed in alphabetical order):
-
-<ul type="square">
- <li>BSD/OS 1.1 (Intel Pentium), gcc </li>
- <li>Digital UNIX V3.2 148 (Alpha), gcc/cc </li>
- <li>Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc </li>
- <li>IBM AIX 1 4 (RS/6000), gcc </li>
- <li>Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc </li>
- <li>Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc </li>
- <li>Sun SunOS 4.1.4 (SPARC), gcc </li>
-</ul>
-
-<p>Once you've built the kit, follow the directions in <a href="#S4">Section 4</a> to
-bring up your Web server and run the example applications.</p>
-
-<h3><a NAME="S3">3. Writing applications</a></h3>
-
-<h4><a NAME="S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> </h4>
-
-<p>The <tt>fcgi_stdio</tt> library provides the easiest transition for C CGI programs and
-C CGI programmers to FastCGI. Using this library your application can run using either CGI
-or FastCGI, with the same binary for both situations.</p>
-
-<p>To introduce the <tt>fcgi_stdio</tt> library we give a pair of examples: a tiny CGI
-program and the translation of this program to FastCGI. These two example programs are
-included in the kit.</p>
-
-<p>The CGI program is <tt>examples/tiny-cgi.c</tt>:</p>
-
-<pre>
- #include <stdio.h>
- #include <stdlib.h>
-
- void main(void)
- {
- int count = 0;
- printf("Content-type: text/html\r\n"
- "\r\n"
- "<title>CGI Hello!</title>"
- "<h1>CGI Hello!</h1>"
- "Request number %d running on host <i>%s</i>\n",
- ++count, getenv("SERVER_NAME"));
- }
-</pre>
-
-<p>The key features of this tiny CGI program are:
-
-<ul type="square">
- <li>The program sends data to the Web server by writing to <tt>stdout</tt>, using <tt>printf</tt>
- in this example. The CGI program first sends a <tt>Content-type</tt> header, then a small
- HTML document. The program includes <tt>stdio.h</tt> in order to get access to the <tt>printf</tt>
- function.</li>
- <li>The program obtains parameters provided by the Web server by reading environment
- variables. The CGI program reads the <tt>SERVER_NAME</tt> variable using <tt>getenv</tt>
- and includes the value in the HTML document. The program includes <tt>stdlib.h</tt> in
- order to get access to the <tt>getenv</tt> function.</li>
-</ul>
-
-<p>The <tt>count</tt> variable is degenerate in this example; the CGI program runs a
-single request, so the request number is always one. This variable will be more
-interesting in the FastCGI example.</p>
-
-<p><a NAME="S3.1.1">The</a> corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:</p>
-
-<pre>
- #include "fcgi_stdio.h"
- #include <stdlib.h>
-
- void main(void)
- {
- int count = 0;
- while(FCGI_Accept() >= 0)
- printf("Content-type: text/html\r\n"
- "\r\n"
- "<title>FastCGI Hello!</title>"
- "<h1>FastCGI Hello!</h1>"
- "Request number %d running on host <i>%s</i>\n",
- ++count, getenv("SERVER_NAME"));
- }
-</pre>
-
-<p>The key features of this tiny FastCGI program are:
-
-<ul type="square">
- <li>The program is structured as a loop that begins by calling the function <tt>FCGI_Accept</tt>.
- The <tt>FCGI_Accept</tt> function blocks until a new request arrives for the program to
- execute. The program includes <tt>fcgi_stdio.h</tt> in order to get access to the <tt>FCGI_Accept</tt>
- function.</li>
- <li>Within the loop, <tt>FCGI_Accept</tt> creates a CGI-compatible world. <tt>printf</tt>
- and <tt>getenv</tt> operate just as in the CGI program. <tt>stdin</tt> and <tt>stderr</tt>,
- not used by this tiny program, also operate just as in a CGI program.</li>
-</ul>
-
-<p>The <tt>count</tt> variable increments each time through the loop, so the program
-displays a new request number each time. You can use the reload button in your browser to
-demonstrate this, once you've got the program built and running.</p>
-
-<h4>Building the program</h4>
-
-<p>If you can build <tt>examples/tiny-cgi.c</tt>, it will be straightforward for you to
-build <tt>examples/tiny-fcgi.c</tt>. You need to:
-
-<ul type="square">
- <li>Add the directory containing the <tt>fcgi_stdio.h</tt> header to the compiler's include
- search path. The kit calls this directory <tt>include</tt>.</li>
- <li>Add the library <tt>libfcgi.a</tt> to the linker's command line so that it will be
- searched when linking. The <tt>libfcgi.a</tt> library implements the functions defined in <tt>fcgi_stdio.h</tt>.
- The kit calls the directory containing this library <tt>libfcgi</tt>.</li>
- <li>Determine whether or not the linker on your platform searches the Berkeley socket
- library by default, and if not, add linker directives to force this search.</li>
-</ul>
-
-<p>See <tt>examples/Makefile</tt> (created by <tt>configure</tt>) for a Makefile that
-builds both programs. Autoconf handles the platform-dependent linking issues; to see how,
-examine <tt>configure.in</tt> and <tt>examples/Makefile.in</tt>.</p>
-
-<h4>Running the program</h4>
-<a href="#S4">
-
-<p>Section 4</a> is all about how to run FastCGI applications.</p>
-
-<p>You can use CGI to run application binaries built with the <tt>fcgi_stdio</tt> library.
-The <tt>FCGI_Accept</tt> function tests its environment to determine how the application
-was invoked. If it was invoked as a CGI program, the first call to FCGI_Accept is
-essentially a no-op and the second call returns <tt>-1</tt>. In effect, the request loop
-disappears.</p>
-
-<p>Of course, when a FastCGI application is run using CGI it does not get the benefits of
-FastCGI. For instance, the application exits after servicing a single request, so it
-cannot maintain cached information.</p>
-
-<h4>Implementation details</h4>
-<tt>
-
-<p>fcgi_stdio.h</tt> works by first including <tt>stdio.h</tt>, then defining macros to
-replace essentially all of the types and procedures defined in <tt>stdio.h</tt>. (<tt>stdio.h</tt>
-defines a few procedures that have nothing to do with <tt>FILE *</tt>, such as <tt>sprintf</tt>
-and <tt>sscanf</tt>; <tt>fcgi_stdio.h</tt> doesn't replace these.) For instance, <tt>FILE</tt>
-becomes <tt>FCGI_FILE</tt> and <tt>printf</tt> becomes <tt>FCGI_printf</tt>. You'll only
-see these new names if you read <tt>fcgi_stdio.h</tt> or examine your C source code after
-preprocessing.</p>
-
-<p>Here are some consequences of this implementation technique:
-
-<ul type="square">
- <li>On some platforms the implementation will break if you include <tt>stdio.h</tt> after
- including <tt>fcgi_stdio.h</tt>, because <tt>stdio.h</tt> often defines macros for
- functions such as <tt>getc</tt> and <tt>putc</tt>. Fortunately, on most platforms <tt>stdio.h</tt>
- is protected against multiple includes by lines near the top of the file that look like <pre>
- #ifndef _STDIO_H
- #define _STDIO_H
- </pre>
- <p>The specific symbol used for multiple-include protection, <tt>_STDIO_H</tt> in this
- example, varies from platform to platform. As long as your platform protects <tt>stdio.h</tt>
- against multiple includes, you can forget about this issue.</p>
- </li>
- <li>If your application passes <tt>FILE *</tt> to functions implemented in libraries for
- which you have source code, then you'll want to recompile these libraries with <tt>fcgi_stdio.h</tt>
- included. Most C compilers provide a command-line option for including headers in a
- program being compiled; using such a compiler feature allows you to rebuild your libraries
- without making source changes. For instance the gcc command line <pre>
- gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c
- </pre>
- <p>causes gcc to include <tt>fcgi_stdio.h</tt> before it even begins to read the module <tt>wonderlib.c</tt>.</p>
- </li>
- <li>If your application passes <tt>FILE *</tt> to functions implemented in libraries for
- which you do not have source code, then you'll need to include the headers for these
- libraries <i>before</i> you include <tt>fcgi_stdio.h</tt>. You can't pass the <tt>stdin</tt>,
- <tt>stdout</tt>, or <tt>stderr</tt> streams produced by <tt>FCGI_Accept</tt> to any
- functions implemented by these libraries. You can pass a stream on a Unix file to a
- library function by following this pattern: <pre>
- FILE *myStream = fopen(path, "r");
- answer = MungeStream(FCGI_ToFile(myStream));
- </pre>
- <p>Here <tt>MungeStream</tt> is a library function that you can't recompile and <tt>FCGI_ToFile</tt>
- is a macro that converts from <tt>FCGI_FILE *</tt> to <tt>FILE *</tt>. The macro <tt>FCGI_ToFile</tt>
- is defined in <tt>fcgi_stdio.h</tt>.</p>
- </li>
-</ul>
-
-<h4>Converting CGI programs</h4>
-
-<p>The main task in converting a CGI program into a FastCGI program is separating the code
-that needs to execute once, initializing the program, from the code that needs to run for
-each request. In our tiny example, initializing the <tt>count</tt> variable is outside the
-loop, while incrementing the <tt>count</tt> variable goes inside.</p>
-
-<p>Retained application state may be an issue. You must ensure that any application state
-created in processing one request has no unintended effects on later requests. FastCGI
-offers the possibility of significant application performance improvements, through
-caching; it is up to you to make the caches work correctly.</p>
-
-<p>Storage leaks may be an issue. Many CGI programs don't worry about storage leaks
-because the programs don't run for long enough for bloating to be a problem. When
-converting to FastCGI, you can either use a tool such as <a href="http://www.pure.com/"><i>Purify</i></a>
-from Pure Software to discover and fix storage leaks, or you can run a C garbage collector
-such as <a href="http://www.geodesic.com/"><i>Great Circle</i></a> from Geodesic Systems.</p>
-
-<h4>Limitations</h4>
-
-<p>Currently there are some limits to the compatibility provided by the <tt>fcgi_stdio</tt>
-library:
-
-<ul type="square">
- <li>The library does not provide FastCGI versions of the functions <tt>fscanf</tt> and <tt>scanf</tt>.
- If you wish to apply <tt>fscanf</tt> or <tt>scanf</tt> to <tt>stdin</tt> of a FastCGI
- program, the workaround is to read lines or other natural units into memory and then call <tt>sscanf</tt>.
- If you wish to apply <tt>fscanf</tt> to a stream on a Unix file, the workaround is to
- follow the pattern: <pre>
- FILE *myStream = fopen(path, "r");
- count = fscanf(FCGI_ToFile(myStream), format, ...);
- </pre>
- </li>
-</ul>
-
-<h4>Reference documentation</h4>
-
-<p>The <a href="FCGI_Accept.3"><tt>FCGI_Accept</tt> manpage</a>, <tt>doc/FCGI_Accept.3</tt>,
-describes the function in the traditional format.</p>
-
-<p>The <a href="FCGI_Finish.3"><tt>FCGI_Finish</tt></a> (<tt>doc/FCGI_Finish.3</tt>), <a
-href="FCGI_SetExitStatus.3"><tt>FCGI_SetExitStatus</tt></a> (<tt>doc/FCGI_SetExitStatus.3</tt>),
-and <a href="FCGI_StartFilterData.3"><tt>FCGI_StartFilterData</tt></a> (<tt>doc/FCGI_StartFilterData.3</tt>)
-manpages document capabilities of the <tt>fcgi-stdio</tt> library that are not illustrated
-above.</p>
-
-<h4><a NAME="S3.2">3.2 Using the <tt>fcgiapp</tt> library</a></h4>
-
-<p>The <tt>fcgiapp</tt> library is a second C library for FastCGI. It does not provide the
-high degree of source code compatibility provided by <tt>fcgi_stdio</tt>; in return, it
-does not make such heavy use of <tt>#define</tt>. <tt>fcgi_stdio</tt> is implemented as a
-thin layer on top of <tt>fcgiapp</tt>.</p>
-
-<p>Applications built using the <tt>fcgiapp</tt> library cannot run as CGI programs; that
-feature is provided at the <tt>fcgi_stdio</tt> level.</p>
-
-<p>Functions defined in <tt>fcgiapp</tt> are named using the prefix <tt>FCGX_</tt> rather
-than <tt>FCGI_</tt>. For instance, <tt>FCGX_Accept</tt> is the <tt>fcgiapp</tt> version of
-<tt>FCGI_Accept</tt>.</p>
-
-<p>Documentation of the <tt>fcgiapp</tt> library takes the form of extensive comments in
-the header file <tt>include/fcgiapp.h</tt>. The sample programs <tt>examples/tiny-fcgi2.c</tt>
-and <tt>examples/echo2.c</tt> illustrate how to use <tt>fcgiapp</tt>.</p>
-
-<h4><a NAME="S3.3">3.3 Using Perl and Tcl</a></h4>
-
-<p>A major advantage of the FastCGI approach to high-performance Web applications is its
-language-neutrality. CGI scripts written in popular languages such as Perl and Tcl can be
-evolved into high-performance FastCGI applications.</p>
-
-<p>We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since
-Perl and Tcl are conventional C applications and <tt>fcgi_stdio</tt> was designed for
-converting conventional C applications. Essentially no source code changes were required
-in these programs; a small amount of code was added in order to make <tt>FCGI_Accept</tt>
-and other FastCGI primitives available in these languages. And because these interpreters
-were developed using <tt>fcgi_stdio</tt>, they run standard Perl and Tcl applications
-(e.g. CGI scripts) as well as FastCGI applications.</p>
-
-<p>See the <a href="http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a> Web page
-for downloadable Perl and Tcl binaries for selected platforms. Because many users of Perl
-and Tcl run extended versions of these languages, the kit includes separate companion
-documents describing <a href="fcgi-perl.htm">how to build FastCGI-integrated Perl</a> and <a
-href="fcgi-tcl.htm">how to build FastCGI-integrated Tcl</a>.</p>
-
-<p>Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:</p>
-
-<pre>
-#!./perl
-use FCGI;
-$count = 0;
-while(FCGI::accept() >= 0) {
- print("Content-type: text/html\r\n\r\n",
- "<title>FastCGI Hello! (Perl)</title>\n",
- "<h1>FastCGI Hello! (Perl)</h1>\n";
- "Request number ", ++$count,
- " running on host <i>";$env(SERVER_NAME)</i>");
-}
-</pre>
-
-<pre>
-#!./tclsh
-set count 0
-while {[FCGI_Accept] >= 0 } {
- incr count
- puts -nonewline "Content-type: text/html\r\n\r\n"
- puts "<title>FastCGI Hello! (Tcl)</title>"
- puts "<h1>FastCGI Hello! (Tcl)</h1>"
- puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
-}
-</pre>
-
-<p>Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from
-converting a C CGI application to FastCGI. You separate the portion of the application
-that performs one-time initialization from the portion that performs per-request
-processing. You put the per-request processing into a loop controlled by <tt>FCGI::accept</tt>
-(Perl) or <tt>FCGI_Accept</tt> (Tcl). </p>
-
-<h4><a NAME="S3.4">3.4 Using Java</a></h4>
-
-<p>Java is not just for browser-based applets. It is already suitable for writing some Web
-server applications, and its range of applicability will only grow as Java compilers and
-other Java tools improve. Java's modules, garbage collection, and threads are especially
-valuable for writing long-lived application servers.</p>
-
-<p>The <tt>FCGIInterface</tt> class provides facilities for Java applications analogous to
-what <tt>fcgi_stdio</tt> provides for C applications. Using this library your Java
-application can run using either CGI or FastCGI.</p>
-
-<p>The kit includes separate companion document on <a href="fcgi-java.htm">using FastCGI
-with Java</a>. The source code for FastCGI classes is contained in directory <tt>java/src</tt>
-and the compiled code in <tt>java/classes</tt>.</p>
-
-<p>Here is the Java version of <tt>tiny-fcgi</tt>:</p>
-
-<pre>
-import FCGIInterface;
-
-class TinyFCGI {
- public static void main (String args[]) {
- int count = 0;
- while(new FCGIInterface().FCGIaccept()>= 0) {
- count ++;
- System.out.println("Content-type: text/html\r\n\r\n");
- System.out.println(
- "<title>FastCGI Hello! (Java)</title>");
- System.out.println("<h1>FastCGI Hello! (Java)</h1>");
- System.out.println(
- "request number " + count + " running on host <i>" +
- System.getProperty("SERVER_NAME") + "</i>");
- }
- }
-}
-</pre>
-
-<h3><a NAME="S4">4. Running applications</a></h3>
-
-<h3><a NAME="S4.1">4.1 Using a Web server that supports FastCGI</a></h3>
-
-<p>For a current listing of Web servers that support FastCGI, see the <a
-HREF="http://www.fastcgi.com/servers">www.fastcgi.com/servers</a> Web page.</p>
-
-<p>All of the Web servers that support FastCGI perform management of FastCGI applications.
-You don't need to start and stop FastCGI applications; the Web server takes care of this.
-If an application process should crash, the Web server restarts it.</p>
-
-<p>Web servers support FastCGI via new configuration directives. Since these directives
-are server-specific, get more information from the documentation that accompanies each
-server.</p>
-
-<p>The directory <a HREF="../examples/conf"><tt>examples/conf</tt></a> contains config
-files designed to run the example programs included in the FastCGI Developer's Kit. Each
-config file contains specific installation instructions.</p>
-
-<p>The more advanced example programs take advantage of special features of the Open
-Market Secure WebServer, such as anonymous ticketing and support for the Authorizer role.
-If you don't have this server, download a <a
-HREF="http://www.openmarket.com/store/eval/swsg.htm">free evaluation copy</a> to run the
-examples.</p>
-
-<h3><a NAME="S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3>
-
-<p>The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications using any Web
-server that supports CGI.</p>
-
-<p>Here is how <tt>cgi-fcgi</tt> works. <tt>cgi-fcgi</tt> is a standard CGI program that
-uses Unix domain or TCP/IP sockets to communicate with a FastCGI application. <tt>cgi-fcgi</tt>
-takes the path name or host/port name of a listening socket as a parameter and <tt>connect</tt>s
-to the FastCGI application listening on that socket. <tt>cgi-fcgi</tt> then forwards the
-CGI environment variables and <tt>stdin</tt> data to the FastCGI application, and forwards
-the <tt>stdout</tt> and <tt>stderr</tt> data from the FastCGI application to the Web
-server. When the FastCGI application signals the end of its response, <tt>cgi-fcgi</tt>
-flushes its buffers and exits.</p>
-
-<p>Obviously, having <tt>cgi-fcgi</tt> is not as good as having a server with integrated
-FastCGI support:
-
-<ul>
- <li>Communication is slower than with a Web server that avoids the fork/exec overhead on
- every FastCGI request. </li>
- <li><tt>cgi-fcgi</tt> does not perform application management, so you need to provide this
- yourself. </li>
- <li><tt>cgi-fcgi</tt> supports only the Responder role. </li>
-</ul>
-
-<p>But <tt>cgi-fcgi</tt> does allow you to develop applications that retain state in
-memory between connections, which often provides a major performance boost over normal
-CGI. And all the applications you develop using <tt>cgi-fcgi</tt> will work with Web
-servers that have integrated support for FastCGI.</p>
-
-<p>The file <tt>examples/tiny-fcgi.cgi</tt> demonstrates a way to use <tt>cgi-fcgi</tt> to
-run a typical application, in this case the <tt>examples/tiny-fcgi</tt> application: </p>
-
-<pre>
- #!../cgi-fcgi/cgi-fcgi -f
- -connect sockets/tiny-fcgi tiny-fcgi
-</pre>
-
-<p>On most Unix platforms, executing this command-interpreter file runs <tt>cgi-fcgi</tt>
-with arguments <tt>-f</tt> and <tt>examples/tiny-fcgi.cgi</tt>. (Beware: On some Unix
-platforms, including HP-UX, the first line of a command-interpreter file cannot contain
-more than 32 characters, including the newline; you may need to install the <tt>cgi-fcgi</tt>
-application in a standard place like <tt>/usr/local/bin</tt> or create a symbolic link to
-the <tt>cgi-fcgi</tt> application in the directory containing your application.) The <tt>cgi-fcgi</tt>
-program reads the command-interpreter file and connects to the FastCGI application whose
-listening socket is <tt>examples/sockets/tiny-fcgi</tt>.</p>
-
-<p>Continuing the example, if <tt>cgi-fcgi</tt>'s connection attempt fails, it creates a
-new process running the program <tt>examples/tiny-fcgi</tt> and listening on socket <tt>examples/sockets/tiny-fcgi</tt>.
-Then <tt>cgi-fcgi</tt> retries the connection attempt, which now should succeed.</p>
-
-<p>The <tt>cgi-fcgi</tt> program has two other modes of operation. In one mode it connects
-to applications but does not start them; in the other it starts applications but does not
-connect to them. These modes are required when using TCP/IP. The <a href="cgi-fcgi.1"><tt>cgi-fcgi</tt>
-manpage</a>, <tt>doc/cgi-fcgi.1</tt>, tells the full story.</p>
-
-<p>To run the example applications using <tt>cgi-fcgi</tt>, start your Web server and give
-it the directory <tt>fcgi-devel-kit</tt> as the root of its URL space. If the machine
-running your server is called <tt>bowser</tt> and your server is running on port <tt>8888</tt>,
-you'd then open the URL <tt>http://bowser:8888/index.html</tt> to reach the kit's index
-page. Now the links on the index page that run example applications via <tt>cgi-fcgi</tt>
-should be active.</p>
-
-<h3><a NAME="S5">5. Known problems</a></h3>
-
-<p>On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file
-systems. The symptom when using cgi-fcgi is an exit status of 38 (<tt>ENOTSOCK</tt>:
-socket operation on non-socket), but cgi-fcgi may dump core in this case when compiled
-optimized. Work-around: Store your Unix domain listening sockets on a non NFS file system,
-upgrade to Digital UNIX 3.2, or use TCP sockets.</p>
-
-<p>On AIX there's a problem with shared listening sockets. The symptoms can include
-application core dumps and kernel panic. Work-around: Run a single FastCGI application
-server per listening socket.</p>
-
-<h3><a NAME="S6">6. Getting support</a></h3>
-
-<p>The mailing list <tt>fastcgi-developers@idle.com</tt> is used for discussions of issues
-in developing FastCGI applications. Topics include announcement of FastCGI-capable Web
-servers or changes to such servers, announcement of new application libraries or changes
-to such libraries, announcement of known bugs, discussion of design trade-offs in FastCGI
-application programming, and discussion of development plans and experiences. To join the
-list, send a message to <a href="mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@idle.com</a>
-with a message body consisting of the word "subscribe" (leaving off the quotes).</p>
-
-<p>A link to a mail archive can be found on the FastCGI home page, <a
-href="http://www.fastcgi.com">http://www.fastcgi.com</a></p>
-
-<hr>
-
-<address>
- © 1996, Open Market, Inc. / mbrown@openmarket.com
-</address>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Developer's Kit\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #FFFFFF;\r
+ color: #000000;\r
+ }\r
+ :link { color: #cc0000 }\r
+ :visited { color: #555555 }\r
+ :active { color: #000011 }\r
+ h5.c3 {text-align: center}\r
+ h3.c2 {text-align: center}\r
+ p.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <P CLASS="c1">\r
+ <IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"><BR CLEAR="all">\r
+ </P>\r
+ <H3 CLASS="c2">\r
+ FastCGI Developer's Kit\r
+ </H3>\r
+ <!--Copyright (c) 1996 Open Market, Inc. -->\r
+ <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->\r
+ <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->\r
+ <P CLASS="c1">\r
+ Mark R. Brown<BR>\r
+ Open Market, Inc.<BR>\r
+ </P>\r
+ <P CLASS="c1">\r
+ Document Version: 1.08<BR>\r
+ 11 June 1996<BR>\r
+ </P>\r
+ <H5 CLASS="c3">\r
+ Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>\r
+ Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=\r
+ "http://www.openmarket.com/">http://www.openmarket.com/</A><BR>\r
+ $Id: fcgi-devel-kit.htm,v 1.4 2001/11/27 01:03:47 robs Exp $<BR>\r
+ </H5>\r
+ <HR>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ <A HREF="#S1">1. Introduction</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S2">2. Getting started</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S3">3. Writing applications</A> \r
+ <UL TYPE="square">\r
+ <LI>\r
+ <A HREF="#S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S3.3">3.3 Using Perl and Tcl</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S3.4">3.4 Using Java</A>\r
+ </LI>\r
+ </UL>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S4">4. Running applications</A> \r
+ <UL TYPE="square">\r
+ <LI>\r
+ <A HREF="#S4.1">4.1 Using a Web server that supports FastCGI</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>\r
+ </LI>\r
+ </UL>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S5">5. Known problems</A>\r
+ </LI>\r
+ <LI>\r
+ <A HREF="#S6">6. Getting support</A>\r
+ </LI>\r
+ </UL>\r
+ <HR>\r
+ <H3>\r
+ <A NAME="S1">1. Introduction</A>\r
+ </H3>\r
+ <P>\r
+ FastCGI is an open extension to CGI that provides high performance for all Internet applications without the\r
+ penalties of Web server APIs.\r
+ </P>\r
+ <P>\r
+ FastCGI is designed to be layered on top of existing Web server APIs. For instance, the <TT>mod_fastcgi</TT>\r
+ Apache module adds FastCGI support to the Apache server. FastCGI can also be used, with reduced functionality\r
+ and reduced performance, on any Web server that supports CGI.\r
+ </P>\r
+ <P>\r
+ This FastCGI Developer's Kit is designed to make developing FastCGI applications easy. The kit currently\r
+ supports FastCGI applications written in C/C++, Perl, Tcl, and Java.\r
+ </P>\r
+ <P>\r
+ This document:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ Describes how to configure and build the kit for your development platform.\r
+ </LI>\r
+ <LI>\r
+ Tells how to write applications using the libraries in the kit.\r
+ </LI>\r
+ <LI>\r
+ Tells how to run applications using Web servers that support FastCGI or using any Web server and\r
+ <TT>cgi-fcgi</TT>.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ The kit includes a <A HREF="fastcgi-whitepaper/fastcgi.htm">technical white paper</A>,\r
+ <TT>doc/fastcgi-whitepaper/fastcgi.htm</TT>. You should read at least the first three sections of the\r
+ technical white paper before starting to write FastCGI applications. The <A HREF="fcgi-perf.htm">performance\r
+ paper</A> will help you understand how application design affects performance with FastCGI.\r
+ </P>\r
+ <P>\r
+ The <A HREF="fcgi-spec.html">FastCGI Specification</A>, <TT>doc/fcgi-spec.html</TT>, defines the interface\r
+ between a FastCGI application and a Web server that supports FastCGI. The software in the kit implements the\r
+ specification. You don't need to read the specification in order to write applications.\r
+ </P>\r
+ <P>\r
+ Additional information is provided in the <A HREF="http://fastcgi.com/docs/faq.html">FAQ</A> document, which\r
+ contains frequently asked questions about application development using FastCGI, as well as some general\r
+ information.\r
+ </P>\r
+ <P>\r
+ Experience with CGI programming will be extremely valuable in writing FastCGI applications. If you don't\r
+ have enough experience with CGI programming, you should read one of the popular books on the topic or study\r
+ the <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</A>. For a more formal treatment of CGI/1.1 see\r
+ the <A HREF="http://cgi-spec.golux.com/">Internet Draft CGI 1.1 Specification</A>.\r
+ </P>\r
+ <H3>\r
+ <A NAME="S2">2. Getting started</A>\r
+ </H3>\r
+ <P>\r
+ The kit is a compressed tar (tar.Z) file, distributed via the <A HREF="http://fastcgi.com/">fastcgi.com</A>\r
+ Web page. Unpacking the tar file creates a new directory <TT>fcgi-devel-kit</TT>.\r
+ </P>\r
+ <P>\r
+ Open the kit's index page, <TT>fcgi-devel-kit/index.html</TT>, using the "Open File" command in\r
+ your Web browser. The index page gives you an overview of the kit structure and helps you navigate the kit.\r
+ The index page also contains links that run some example applications, but the applications won't work\r
+ when index.html is opened using the "Open File" command because they aren't aren't being\r
+ accessed through a Web server.\r
+ </P>\r
+ <P>\r
+ In order to use the kit in earnest you'll need a Web server that you control, a Web server running with\r
+ your user ID. The Web server will be starting FastCGI applications that you will need to debug; this will be a\r
+ lot more convenient for you if these processes run with your user ID. It is best to have a Web server that\r
+ supports FastCGI. <A HREF="#S4">Section 4</A> discusses Web server issues.\r
+ </P>\r
+ <P>\r
+ If you can, keep the kit on a file system accessible from your personal workstation, do your builds on your\r
+ workstation, and run your Web server on your workstation. If that's not possible, arrange a configuration\r
+ such that the kit is accessible from the machine that's going to run your Web server, and build the kit\r
+ and your applications on a machine that's configured exactly the same way (same processor architecture,\r
+ operating system, etc.) as the machine that's going to run your Web server.\r
+ </P>\r
+ <P>\r
+ To build the kit you execute this sequence of commands in the <TT>fcgi-devel-kit</TT> directory:\r
+ </P>\r
+<PRE>\r
+ % ./configure\r
+ % make\r
+</PRE>\r
+ <P>\r
+ We've built and exercised the kit on these platforms (listed in alphabetical order):\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ BSD/OS 1.1 (Intel Pentium), gcc\r
+ </LI>\r
+ <LI>\r
+ Digital UNIX V3.2 148 (Alpha), gcc/cc\r
+ </LI>\r
+ <LI>\r
+ Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc\r
+ </LI>\r
+ <LI>\r
+ IBM AIX 1 4 (RS/6000), gcc\r
+ </LI>\r
+ <LI>\r
+ Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc\r
+ </LI>\r
+ <LI>\r
+ Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc\r
+ </LI>\r
+ <LI>\r
+ Sun SunOS 4.1.4 (SPARC), gcc\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ Once you've built the kit, follow the directions in <A HREF="#S4">Section 4</A> to bring up your Web\r
+ server and run the example applications.\r
+ </P>\r
+ <H3>\r
+ <A NAME="S3">3. Writing applications</A>\r
+ </H3>\r
+ <H4>\r
+ <A NAME="S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>\r
+ </H4>\r
+ <P>\r
+ The <TT>fcgi_stdio</TT> library provides the easiest transition for C CGI programs and C CGI programmers to\r
+ FastCGI. Using this library your application can run using either CGI or FastCGI, with the same binary for\r
+ both situations.\r
+ </P>\r
+ <P>\r
+ To introduce the <TT>fcgi_stdio</TT> library we give a pair of examples: a tiny CGI program and the\r
+ translation of this program to FastCGI. These two example programs are included in the kit.\r
+ </P>\r
+ <P>\r
+ The CGI program is <TT>examples/tiny-cgi.c</TT>:\r
+ </P>\r
+<PRE>\r
+ #include <stdio.h>\r
+ #include <stdlib.h>\r
+\r
+ void main(void)\r
+ {\r
+ int count = 0;\r
+ printf("Content-type: text/html\r\n"\r
+ "\r\n"\r
+ "<title>CGI Hello!</title>"\r
+ "<h1>CGI Hello!</h1>"\r
+ "Request number %d running on host <i>%s</i>\n",\r
+ ++count, getenv("SERVER_NAME"));\r
+ }\r
+</PRE>\r
+ <P>\r
+ The key features of this tiny CGI program are:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ The program sends data to the Web server by writing to <TT>stdout</TT>, using <TT>printf</TT> in this\r
+ example. The CGI program first sends a <TT>Content-type</TT> header, then a small HTML document. The\r
+ program includes <TT>stdio.h</TT> in order to get access to the <TT>printf</TT> function.\r
+ </LI>\r
+ <LI>\r
+ The program obtains parameters provided by the Web server by reading environment variables. The CGI program\r
+ reads the <TT>SERVER_NAME</TT> variable using <TT>getenv</TT> and includes the value in the HTML document.\r
+ The program includes <TT>stdlib.h</TT> in order to get access to the <TT>getenv</TT> function.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ The <TT>count</TT> variable is degenerate in this example; the CGI program runs a single request, so the\r
+ request number is always one. This variable will be more interesting in the FastCGI example.\r
+ </P>\r
+ <P>\r
+ <A NAME="S3.1.1">The</A> corresponding FastCGI program is <TT>examples/tiny-fcgi.c</TT>:\r
+ </P>\r
+<PRE>\r
+ #include "fcgi_stdio.h"\r
+ #include <stdlib.h>\r
+\r
+ void main(void)\r
+ {\r
+ int count = 0;\r
+ while(FCGI_Accept() >= 0)\r
+ printf("Content-type: text/html\r\n"\r
+ "\r\n"\r
+ "<title>FastCGI Hello!</title>"\r
+ "<h1>FastCGI Hello!</h1>"\r
+ "Request number %d running on host <i>%s</i>\n",\r
+ ++count, getenv("SERVER_NAME"));\r
+ }\r
+</PRE>\r
+ <P>\r
+ The key features of this tiny FastCGI program are:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ The program is structured as a loop that begins by calling the function <TT>FCGI_Accept</TT>. The\r
+ <TT>FCGI_Accept</TT> function blocks until a new request arrives for the program to execute. The program\r
+ includes <TT>fcgi_stdio.h</TT> in order to get access to the <TT>FCGI_Accept</TT> function.\r
+ </LI>\r
+ <LI>\r
+ Within the loop, <TT>FCGI_Accept</TT> creates a CGI-compatible world. <TT>printf</TT> and <TT>getenv</TT>\r
+ operate just as in the CGI program. <TT>stdin</TT> and <TT>stderr</TT>, not used by this tiny program, also\r
+ operate just as in a CGI program.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ The <TT>count</TT> variable increments each time through the loop, so the program displays a new request\r
+ number each time. You can use the reload button in your browser to demonstrate this, once you've got the\r
+ program built and running.\r
+ </P>\r
+ <H4>\r
+ Building the program\r
+ </H4>\r
+ <P>\r
+ If you can build <TT>examples/tiny-cgi.c</TT>, it will be straightforward for you to build\r
+ <TT>examples/tiny-fcgi.c</TT>. You need to:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ Add the directory containing the <TT>fcgi_stdio.h</TT> header to the compiler's include search path.\r
+ The kit calls this directory <TT>include</TT>.\r
+ </LI>\r
+ <LI>\r
+ Add the library <TT>libfcgi.a</TT> to the linker's command line so that it will be searched when\r
+ linking. The <TT>libfcgi.a</TT> library implements the functions defined in <TT>fcgi_stdio.h</TT>. The kit\r
+ calls the directory containing this library <TT>libfcgi</TT>.\r
+ </LI>\r
+ <LI>\r
+ Determine whether or not the linker on your platform searches the Berkeley socket library by default, and\r
+ if not, add linker directives to force this search.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ See <TT>examples/Makefile</TT> (created by <TT>configure</TT>) for a Makefile that builds both programs.\r
+ Autoconf handles the platform-dependent linking issues; to see how, examine <TT>configure.in</TT> and\r
+ <TT>examples/Makefile.in</TT>.\r
+ </P>\r
+ <H4>\r
+ Running the program\r
+ </H4>\r
+ <P>\r
+ <A HREF="#S4">Section 4</A> is all about how to run FastCGI applications.\r
+ </P>\r
+ <P>\r
+ You can use CGI to run application binaries built with the <TT>fcgi_stdio</TT> library. The\r
+ <TT>FCGI_Accept</TT> function tests its environment to determine how the application was invoked. If it was\r
+ invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns\r
+ <TT>-1</TT>. In effect, the request loop disappears.\r
+ </P>\r
+ <P>\r
+ Of course, when a FastCGI application is run using CGI it does not get the benefits of FastCGI. For instance,\r
+ the application exits after servicing a single request, so it cannot maintain cached information.\r
+ </P>\r
+ <H4>\r
+ Implementation details\r
+ </H4>\r
+ <P>\r
+ <TT>fcgi_stdio.h</TT> works by first including <TT>stdio.h</TT>, then defining macros to replace essentially\r
+ all of the types and procedures defined in <TT>stdio.h</TT>. (<TT>stdio.h</TT> defines a few procedures that\r
+ have nothing to do with <TT>FILE *</TT>, such as <TT>sprintf</TT> and <TT>sscanf</TT>; <TT>fcgi_stdio.h</TT>\r
+ doesn't replace these.) For instance, <TT>FILE</TT> becomes <TT>FCGI_FILE</TT> and <TT>printf</TT> becomes\r
+ <TT>FCGI_printf</TT>. You'll only see these new names if you read <TT>fcgi_stdio.h</TT> or examine your C\r
+ source code after preprocessing.\r
+ </P>\r
+ <P>\r
+ Here are some consequences of this implementation technique:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ On some platforms the implementation will break if you include <TT>stdio.h</TT> after including\r
+ <TT>fcgi_stdio.h</TT>, because <TT>stdio.h</TT> often defines macros for functions such as <TT>getc</TT>\r
+ and <TT>putc</TT>. Fortunately, on most platforms <TT>stdio.h</TT> is protected against multiple includes\r
+ by lines near the top of the file that look like \r
+<PRE>\r
+ #ifndef _STDIO_H\r
+ #define _STDIO_H\r
+ \r
+</PRE>\r
+ <P>\r
+ The specific symbol used for multiple-include protection, <TT>_STDIO_H</TT> in this example, varies from\r
+ platform to platform. As long as your platform protects <TT>stdio.h</TT> against multiple includes, you\r
+ can forget about this issue.\r
+ </P>\r
+ </LI>\r
+ <LI>\r
+ If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you have source\r
+ code, then you'll want to recompile these libraries with <TT>fcgi_stdio.h</TT> included. Most C\r
+ compilers provide a command-line option for including headers in a program being compiled; using such a\r
+ compiler feature allows you to rebuild your libraries without making source changes. For instance the gcc\r
+ command line \r
+<PRE>\r
+ gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c\r
+ \r
+</PRE>\r
+ <P>\r
+ causes gcc to include <TT>fcgi_stdio.h</TT> before it even begins to read the module\r
+ <TT>wonderlib.c</TT>.\r
+ </P>\r
+ </LI>\r
+ <LI>\r
+ If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you do not have\r
+ source code, then you'll need to include the headers for these libraries <I>before</I> you include\r
+ <TT>fcgi_stdio.h</TT>. You can't pass the <TT>stdin</TT>, <TT>stdout</TT>, or <TT>stderr</TT> streams\r
+ produced by <TT>FCGI_Accept</TT> to any functions implemented by these libraries. You can pass a stream on\r
+ a Unix file to a library function by following this pattern: \r
+<PRE>\r
+ FILE *myStream = fopen(path, "r");\r
+ answer = MungeStream(FCGI_ToFile(myStream));\r
+ \r
+</PRE>\r
+ <P>\r
+ Here <TT>MungeStream</TT> is a library function that you can't recompile and <TT>FCGI_ToFile</TT> is\r
+ a macro that converts from <TT>FCGI_FILE *</TT> to <TT>FILE *</TT>. The macro <TT>FCGI_ToFile</TT> is\r
+ defined in <TT>fcgi_stdio.h</TT>.\r
+ </P>\r
+ </LI>\r
+ </UL>\r
+ <H4>\r
+ Converting CGI programs\r
+ </H4>\r
+ <P>\r
+ The main task in converting a CGI program into a FastCGI program is separating the code that needs to execute\r
+ once, initializing the program, from the code that needs to run for each request. In our tiny example,\r
+ initializing the <TT>count</TT> variable is outside the loop, while incrementing the <TT>count</TT> variable\r
+ goes inside.\r
+ </P>\r
+ <P>\r
+ Retained application state may be an issue. You must ensure that any application state created in processing\r
+ one request has no unintended effects on later requests. FastCGI offers the possibility of significant\r
+ application performance improvements, through caching; it is up to you to make the caches work correctly.\r
+ </P>\r
+ <P>\r
+ Storage leaks may be an issue. Many CGI programs don't worry about storage leaks because the programs\r
+ don't run for long enough for bloating to be a problem. When converting to FastCGI, you can either use a\r
+ tool such as <A HREF="http://www.pure.com/"><I>Purify</I></A> from Pure Software to discover and fix storage\r
+ leaks, or you can run a C garbage collector such as <A HREF="http://www.geodesic.com/"><I>Great Circle</I></A>\r
+ from Geodesic Systems.\r
+ </P>\r
+ <H4>\r
+ Limitations\r
+ </H4>\r
+ <P>\r
+ Currently there are some limits to the compatibility provided by the <TT>fcgi_stdio</TT> library:\r
+ </P>\r
+ <UL TYPE="square">\r
+ <LI>\r
+ The library does not provide FastCGI versions of the functions <TT>fscanf</TT> and <TT>scanf</TT>. If you\r
+ wish to apply <TT>fscanf</TT> or <TT>scanf</TT> to <TT>stdin</TT> of a FastCGI program, the workaround is\r
+ to read lines or other natural units into memory and then call <TT>sscanf</TT>. If you wish to apply\r
+ <TT>fscanf</TT> to a stream on a Unix file, the workaround is to follow the pattern: \r
+<PRE>\r
+ FILE *myStream = fopen(path, "r");\r
+ count = fscanf(FCGI_ToFile(myStream), format, ...);\r
+ \r
+</PRE>\r
+ </LI>\r
+ </UL>\r
+ <H4>\r
+ Reference documentation\r
+ </H4>\r
+ <P>\r
+ The <A HREF="FCGI_Accept.3"><TT>FCGI_Accept</TT> manpage</A>, <TT>doc/FCGI_Accept.3</TT>, describes the\r
+ function in the traditional format.\r
+ </P>\r
+ <P>\r
+ The <A HREF="FCGI_Finish.3"><TT>FCGI_Finish</TT></A> (<TT>doc/FCGI_Finish.3</TT>), <A HREF=\r
+ "FCGI_SetExitStatus.3"><TT>FCGI_SetExitStatus</TT></A> (<TT>doc/FCGI_SetExitStatus.3</TT>), and <A HREF=\r
+ "FCGI_StartFilterData.3"><TT>FCGI_StartFilterData</TT></A> (<TT>doc/FCGI_StartFilterData.3</TT>) manpages\r
+ document capabilities of the <TT>fcgi-stdio</TT> library that are not illustrated above.\r
+ </P>\r
+ <H4>\r
+ <A NAME="S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>\r
+ </H4>\r
+ <P>\r
+ The <TT>fcgiapp</TT> library is a second C library for FastCGI. It does not provide the high degree of source\r
+ code compatibility provided by <TT>fcgi_stdio</TT>; in return, it does not make such heavy use of\r
+ <TT>#define</TT>. <TT>fcgi_stdio</TT> is implemented as a thin layer on top of <TT>fcgiapp</TT>.\r
+ </P>\r
+ <P>\r
+ Applications built using the <TT>fcgiapp</TT> library cannot run as CGI programs; that feature is provided at\r
+ the <TT>fcgi_stdio</TT> level.\r
+ </P>\r
+ <P>\r
+ Functions defined in <TT>fcgiapp</TT> are named using the prefix <TT>FCGX_</TT> rather than <TT>FCGI_</TT>.\r
+ For instance, <TT>FCGX_Accept</TT> is the <TT>fcgiapp</TT> version of <TT>FCGI_Accept</TT>.\r
+ </P>\r
+ <P>\r
+ Documentation of the <TT>fcgiapp</TT> library takes the form of extensive comments in the header file\r
+ <TT>include/fcgiapp.h</TT>. The sample programs <TT>examples/tiny-fcgi2.c</TT> and <TT>examples/echo2.c</TT>\r
+ illustrate how to use <TT>fcgiapp</TT>.\r
+ </P>\r
+ <H4>\r
+ <A NAME="S3.3">3.3 Using Perl and Tcl</A>\r
+ </H4>\r
+ <P>\r
+ A major advantage of the FastCGI approach to high-performance Web applications is its language-neutrality. CGI\r
+ scripts written in popular languages such as Perl and Tcl can be evolved into high-performance FastCGI\r
+ applications.\r
+ </P>\r
+ <P>\r
+ We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since Perl and Tcl are\r
+ conventional C applications and <TT>fcgi_stdio</TT> was designed for converting conventional C applications.\r
+ Essentially no source code changes were required in these programs; a small amount of code was added in order\r
+ to make <TT>FCGI_Accept</TT> and other FastCGI primitives available in these languages. And because these\r
+ interpreters were developed using <TT>fcgi_stdio</TT>, they run standard Perl and Tcl applications (e.g. CGI\r
+ scripts) as well as FastCGI applications.\r
+ </P>\r
+ <P>\r
+ See the <A HREF="http://fastcgi.com">fastcgi.com</A> Web page for more information about the Perl and Tcl\r
+ libraries.\r
+ </P>\r
+ <P>\r
+ Here are the Perl and Tcl versions of <TT>tiny-fcgi</TT>:\r
+ </P>\r
+<PRE>\r
+#!./perl\r
+use FCGI;\r
+$count = 0;\r
+while(FCGI::accept() >= 0) {\r
+ print("Content-type: text/html\r\n\r\n",\r
+ "<title>FastCGI Hello! (Perl)</title>\n",\r
+ "<h1>FastCGI Hello! (Perl)</h1>\n";\r
+ "Request number ", ++$count,\r
+ " running on host <i>";$env(SERVER_NAME)</i>");\r
+}\r
+</PRE>\r
+<PRE>\r
+#!./tclsh\r
+set count 0 \r
+while {[FCGI_Accept] >= 0 } {\r
+ incr count\r
+ puts -nonewline "Content-type: text/html\r\n\r\n"\r
+ puts "<title>FastCGI Hello! (Tcl)</title>"\r
+ puts "<h1>FastCGI Hello! (Tcl)</h1>"\r
+ puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"\r
+}\r
+</PRE>\r
+ <P>\r
+ Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI\r
+ application to FastCGI. You separate the portion of the application that performs one-time initialization from\r
+ the portion that performs per-request processing. You put the per-request processing into a loop controlled by\r
+ <TT>FCGI::accept</TT> (Perl) or <TT>FCGI_Accept</TT> (Tcl).\r
+ </P>\r
+ <H4>\r
+ <A NAME="S3.4">3.4 Using Java</A>\r
+ </H4>\r
+ <P>\r
+ Java is not just for browser-based applets. It is already suitable for writing some Web server applications,\r
+ and its range of applicability will only grow as Java compilers and other Java tools improve. Java's\r
+ modules, garbage collection, and threads are especially valuable for writing long-lived application servers.\r
+ </P>\r
+ <P>\r
+ The <TT>FCGIInterface</TT> class provides facilities for Java applications analogous to what\r
+ <TT>fcgi_stdio</TT> provides for C applications. Using this library your Java application can run using either\r
+ CGI or FastCGI.\r
+ </P>\r
+ <P>\r
+ The kit includes separate companion document on <A HREF="fcgi-java.htm">using FastCGI with Java</A>. The\r
+ source code for FastCGI classes is contained in directory <TT>java/src</TT> and the compiled code in\r
+ <TT>java/classes</TT>.\r
+ </P>\r
+ <P>\r
+ Here is the Java version of <TT>tiny-fcgi</TT>:\r
+ </P>\r
+<PRE>\r
+import FCGIInterface;\r
+\r
+class TinyFCGI { \r
+ public static void main (String args[]) { \r
+ int count = 0;\r
+ while(new FCGIInterface().FCGIaccept()>= 0) {\r
+ count ++;\r
+ System.out.println("Content-type: text/html\r\n\r\n");\r
+ System.out.println(\r
+ "<title>FastCGI Hello! (Java)</title>");\r
+ System.out.println("<h1>FastCGI Hello! (Java)</h1>");\r
+ System.out.println(\r
+ "request number " + count + " running on host <i>" +\r
+ System.getProperty("SERVER_NAME") + "</i>");\r
+ }\r
+ }\r
+}\r
+</PRE>\r
+ <H3>\r
+ <A NAME="S4">4. Running applications</A>\r
+ </H3>\r
+ <H3>\r
+ <A NAME="S4.1">4.1 Using a Web server that supports FastCGI</A>\r
+ </H3>\r
+ <P>\r
+ For a current listing of Web servers that support FastCGI, see the <A HREF=\r
+ "http://fastcgi.com">fastcgi.com</A> Web page.\r
+ </P>\r
+ <P>\r
+ Some of the Web servers that support FastCGI perform management of FastCGI applications. You don't need to\r
+ start and stop FastCGI applications; the Web server takes care of this. If an application process should\r
+ crash, the Web server restarts it.\r
+ </P>\r
+ <P>\r
+ Web servers support FastCGI via new configuration directives. Since these directives are server-specific, get\r
+ more information from the documentation that accompanies each server.\r
+ </P>\r
+ <H3>\r
+ <A NAME="S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>\r
+ </H3>\r
+ <P>\r
+ The program <TT>cgi-fcgi</TT> allows you to run FastCGI applications using any Web server that supports CGI.\r
+ </P>\r
+ <P>\r
+ Here is how <TT>cgi-fcgi</TT> works. <TT>cgi-fcgi</TT> is a standard CGI program that uses Unix domain or\r
+ TCP/IP sockets to communicate with a FastCGI application. <TT>cgi-fcgi</TT> takes the path name or host/port\r
+ name of a listening socket as a parameter and <TT>connect</TT>s to the FastCGI application listening on that\r
+ socket. <TT>cgi-fcgi</TT> then forwards the CGI environment variables and <TT>stdin</TT> data to the FastCGI\r
+ application, and forwards the <TT>stdout</TT> and <TT>stderr</TT> data from the FastCGI application to the Web\r
+ server. When the FastCGI application signals the end of its response, <TT>cgi-fcgi</TT> flushes its buffers\r
+ and exits.\r
+ </P>\r
+ <P>\r
+ Obviously, having <TT>cgi-fcgi</TT> is not as good as having a server with integrated FastCGI support:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ Communication is slower than with a Web server that avoids the fork/exec overhead on every FastCGI request.\r
+ </LI>\r
+ <LI>\r
+ <TT>cgi-fcgi</TT> does not perform application management, so you need to provide this yourself.\r
+ </LI>\r
+ <LI>\r
+ <TT>cgi-fcgi</TT> supports only the Responder role.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ But <TT>cgi-fcgi</TT> does allow you to develop applications that retain state in memory between connections,\r
+ which often provides a major performance boost over normal CGI. And all the applications you develop using\r
+ <TT>cgi-fcgi</TT> will work with Web servers that have integrated support for FastCGI.\r
+ </P>\r
+ <P>\r
+ The file <TT>examples/tiny-fcgi.cgi</TT> demonstrates a way to use <TT>cgi-fcgi</TT> to run a typical\r
+ application, in this case the <TT>examples/tiny-fcgi</TT> application:\r
+ </P>\r
+<PRE>\r
+ #!../cgi-fcgi/cgi-fcgi -f\r
+ -connect sockets/tiny-fcgi tiny-fcgi\r
+</PRE>\r
+ <P>\r
+ On most Unix platforms, executing this command-interpreter file runs <TT>cgi-fcgi</TT> with arguments\r
+ <TT>-f</TT> and <TT>examples/tiny-fcgi.cgi</TT>. (Beware: On some Unix platforms, including HP-UX, the first\r
+ line of a command-interpreter file cannot contain more than 32 characters, including the newline; you may need\r
+ to install the <TT>cgi-fcgi</TT> application in a standard place like <TT>/usr/local/bin</TT> or create a\r
+ symbolic link to the <TT>cgi-fcgi</TT> application in the directory containing your application.) The\r
+ <TT>cgi-fcgi</TT> program reads the command-interpreter file and connects to the FastCGI application whose\r
+ listening socket is <TT>examples/sockets/tiny-fcgi</TT>.\r
+ </P>\r
+ <P>\r
+ Continuing the example, if <TT>cgi-fcgi</TT>'s connection attempt fails, it creates a new process running\r
+ the program <TT>examples/tiny-fcgi</TT> and listening on socket <TT>examples/sockets/tiny-fcgi</TT>. Then\r
+ <TT>cgi-fcgi</TT> retries the connection attempt, which now should succeed.\r
+ </P>\r
+ <P>\r
+ The <TT>cgi-fcgi</TT> program has two other modes of operation. In one mode it connects to applications but\r
+ does not start them; in the other it starts applications but does not connect to them. These modes are\r
+ required when using TCP/IP. The <A HREF="cgi-fcgi.1"><TT>cgi-fcgi</TT> manpage</A>, <TT>doc/cgi-fcgi.1</TT>,\r
+ tells the full story.\r
+ </P>\r
+ <P>\r
+ To run the example applications using <TT>cgi-fcgi</TT>, start your Web server and give it the directory\r
+ <TT>fcgi-devel-kit</TT> as the root of its URL space. If the machine running your server is called\r
+ <TT>bowser</TT> and your server is running on port <TT>8888</TT>, you'd then open the URL\r
+ <TT>http://bowser:8888/index.html</TT> to reach the kit's index page. Now the links on the index page that\r
+ run example applications via <TT>cgi-fcgi</TT> should be active.\r
+ </P>\r
+ <H3>\r
+ <A NAME="S5">5. Known problems</A>\r
+ </H3>\r
+ <P>\r
+ On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file systems. The symptom\r
+ when using cgi-fcgi is an exit status of 38 (<TT>ENOTSOCK</TT>: socket operation on non-socket), but cgi-fcgi\r
+ may dump core in this case when compiled optimized. Work-around: Store your Unix domain listening sockets on a\r
+ non NFS file system, upgrade to Digital UNIX 3.2, or use TCP sockets.\r
+ </P>\r
+ <P>\r
+ On AIX there's a problem with shared listening sockets. The symptoms can include application core dumps\r
+ and kernel panic. Work-around: Run a single FastCGI application server per listening socket.\r
+ </P>\r
+ <H3>\r
+ <A NAME="S6">6. Getting support</A>\r
+ </H3>\r
+ <P>\r
+ The mailing list <TT>fastcgi-developers@idle.com</TT> is used for discussions of issues in developing FastCGI\r
+ applications. Topics include announcement of FastCGI-capable Web servers or changes to such servers,\r
+ announcement of new application libraries or changes to such libraries, announcement of known bugs, discussion\r
+ of design trade-offs in FastCGI application programming, and discussion of development plans and experiences.\r
+ To join the list, send a message to <A HREF=\r
+ "mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@idle.com</A> with a message body\r
+ consisting of the word "subscribe" (leaving off the quotes).\r
+ </P>\r
+ <P>\r
+ A link to a mail archive can be found on the FastCGI home page, <A HREF=\r
+ "http://www.fastcgi.com">http://www.fastcgi.com</A>\r
+ </P>\r
+ <HR>\r
+ <ADDRESS>\r
+ © 1996, Open Market, Inc. / mbrown@openmarket.com\r
+ </ADDRESS>\r
+ </BODY>\r
+</HTML>\r
+\r