<html>
-<head><title>FastCGI Developer's Kit</title>
-</head>
-<body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011"
-vlink="#555555">
+<head>
+<title>FastCGI Developer's Kit</title>
+</head>
-<center>
+<body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011" vlink="#555555">
<a href="/fastcgi/words">
- <img border=0 src="/kit/images/fcgi-hd.gif" alt="[[FastCGI]]"></a>
-</center>
-<br clear=all>
-<h3><center>FastCGI Developer's Kit</center></h3>
+<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. -->
-<center>
-Mark R. Brown<br>
+<p align="center">Mark R. Brown<br>
Open Market, Inc.<br>
-<p>
+</p>
-Document Version: 1.08<br>
+<p align="center">Document Version: 1.08<br>
11 June 1996<br>
-</center>
-<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.1 1997/09/16 15:36:26 stanleyg Exp $ <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><a HREF = "#S2">2. Getting started</a>
- <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><a HREF = "#S3.2">3.2 Using the <tt>fcgiapp</tt> library</a>
- <li><a HREF = "#S3.3">3.3 Using Perl and Tcl</a>
- <li><a HREF = "#S3.4">3.4 Using Java</a>
- </ul>
- <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><a HREF = "#S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a>
- </ul>
- <li><a HREF = "#S5">5. Known problems</a>
- <li><a HREF = "#S6">6. Getting support</a>
+<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>
-<h3><a NAME = "S1">1. Introduction</a></h3>
-
-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>
-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>
-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:
-This document:
-
-<ul type=square>
- <li>Describes how to configure and build the
- kit for your development platform.
-
- <li>Tells how to write applications using the
- libraries in the kit.
-
- <li>Tells how to run applications using Web servers that support
- FastCGI or using any Web server and <tt>cgi-fcgi</tt>.
+<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>
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-To build the kit you execute this sequence of commands
-in the <tt>fcgi-devel-kit</tt> directory:<p>
+<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>
-We've built and exercised the kit on these platforms
-(listed in alphabetical order):<p>
-
-<ul type=square>
- <li>
- BSD/OS 1.1 (Intel Pentium), gcc
- <li>
- Digital UNIX V3.2 148 (Alpha), gcc/cc
- <li>
- Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc
- <li>
- IBM AIX 1 4 (RS/6000), gcc
- <li>
- Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc
- <li>
- Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc
- <li>
- Sun SunOS 4.1.4 (SPARC), gcc
-</ul>
-
-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>
-
+<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>
-<h3><a NAME = "S3">3. Writing applications</a></h3>
+<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>
+<h4><a NAME="S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> </h4>
-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>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>
-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>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>
-The CGI program is <tt>examples/tiny-cgi.c</tt>:<p>
+<p>The CGI program is <tt>examples/tiny-cgi.c</tt>:</p>
<pre>
#include <stdio.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"));
+ 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>
-The key features of this tiny CGI program are:<p>
-
-<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.<p>
- <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.<p>
+<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>
-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>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>
-<a NAME = "S3.1.1">The</a>
-corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:<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 "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"));
+ 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>
-The key features of this tiny FastCGI program are:<p>
-
-<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.<p>
- <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.<p>
-</ul>
+<p>The key features of this tiny FastCGI program are:
-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>
+<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>
-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:<p>
-
-<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>.<p>
- <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>.<p>
- <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.<p>
+<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>
-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>
-
+<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">
-<a href = "#S4">Section 4</a> is all about
-how to run FastCGI applications.<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>Section 4</a> is all about how to run FastCGI applications.</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>
+<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>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>
-
-Here are some
-consequences of this implementation technique:<p>
-
-<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>
+<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>
- 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>
- 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>
+ <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>
- causes gcc to include <tt>fcgi_stdio.h</tt> before it even
- begins to read the module <tt>wonderlib.c</tt>.<p>
- <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");
+ <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>
- 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>
+ <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>
-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>
-
-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>
-
-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>
+<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>
-Currently there are some limits to the compatibility provided
-by the <tt>fcgi_stdio</tt> library:<p>
-
-<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");
+<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>
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:<p>
+<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>");
+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>
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>"
+ 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>
-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>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>
+<h4><a NAME="S3.4">3.4 Using Java</a></h4>
-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>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>
-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 <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>
-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>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>
-Here is the Java version of <tt>tiny-fcgi</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) {
+ while(new FCGIInterface().FCGIaccept()>= 0) {
count ++;
- System.out.println("Content-type: text/html\r\n\r\n");
+ 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>");
+ "<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>");
+ "request number " + count + " running on host <i>" +
+ System.getProperty("SERVER_NAME") + "</i>");
}
}
}
</pre>
-<p>
+<h3><a NAME="S4">4. Running applications</a></h3>
-<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>
-<h3><a NAME = "S4.1">4.1 Using a Web server that supports FastCGI</a></h3>
+<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>
-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>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>
-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>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>
-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 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>
-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>
+<h3><a NAME="S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3>
-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>
+<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>
-<h3><a NAME = "S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3>
-
-The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications
-using any Web server that supports CGI.<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>
-
-Obviously, having <tt>cgi-fcgi</tt> is not as good as having
-a server with integrated FastCGI support:<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><tt>cgi-fcgi</tt> does not perform application management,
- so you need to provide this yourself.
-
- <li><tt>cgi-fcgi</tt> supports only the Responder role.
+ <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>
-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>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>
-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>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>
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-The mailing list <tt>fastcgi-developers@openmarket.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@openmarket.com</a>
-with a message body consisting of the word "subscribe"
-(leaving off the quotes).<p>
-
-Mail sent to this list is archived and available on the
-World-Wide Web at
-<pre>
- http://www.fastcgi.com/mail/
-</pre>
-
-Open Market Secure WebServer customers get FastCGI
-support where they get server support.<p>
-
-
+<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
+ © 1996, Open Market, Inc. / mbrown@openmarket.com
</address>
-
</body>
</html>
projects / catagits/fcgi2.git / commitdiff