-<html>
-<head><title>FastCGI Developer's Kit</title>
-</head>
-
-<body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011"
-vlink="#555555">
-
-<center>
-<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>
-
-<!--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>
-Open Market, Inc.<br>
-<p>
-
-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>
-</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>
-
-<hr>
-
-
-
-<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>
-
-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>
-
-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 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>
-
-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>
-
-<pre>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<HTML>
+ <HEAD>
+ <TITLE>
+ FastCGI Developer's Kit
+ </TITLE>
+<STYLE TYPE="text/css">
+ body {
+ background-color: #FFFFFF;
+ color: #000000;
+ }
+ :link { color: #cc0000 }
+ :visited { color: #555555 }
+ :active { color: #000011 }
+ h5.c3 {text-align: center}
+ h3.c2 {text-align: center}
+ p.c1 {text-align: center}
+</STYLE>
+ </HEAD>
+ <BODY>
+ <P CLASS="c1">
+ <IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"><BR CLEAR="all">
+ </P>
+ <H3 CLASS="c2">
+ FastCGI Developer's Kit
+ </H3>
+ <!--Copyright (c) 1996 Open Market, Inc. -->
+ <!--See the file "LICENSE" for information on usage and redistribution-->
+ <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
+ <P CLASS="c1">
+ Mark R. Brown<BR>
+ Open Market, Inc.<BR>
+ </P>
+ <P CLASS="c1">
+ Document Version: 1.08<BR>
+ 11 June 1996<BR>
+ </P>
+ <H5 CLASS="c3">
+ 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.6 2002/02/25 00:42:59 robs 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:
+ </P>
+ <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://fastcgi.com/docs/faq.html">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://cgi-spec.golux.com/">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://fastcgi.com/">fastcgi.com</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>
-
-
-
-<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>
-
-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>
-
-The CGI program is <tt>examples/tiny-cgi.c</tt>:<p>
-
-<pre>
+</PRE>
+ <P>
+ 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>
+ <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"));
+ 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>
-</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>
-
-<a NAME = "S3.1.1">The</a>
-corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:<p>
-
-<pre>
- #include "fcgi_stdio.h"
+</PRE>
+ <P>
+ 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.
+ </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"));
+ 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>
-
-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>
-</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>
-
-
-<h4>Running the program</h4>
-
-<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>
-
-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>
+</PRE>
+ <P>
+ 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.
+ </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:
+ </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>.
+ </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>
+ <P>
+ <A HREF="#S4">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>
+ <P>
+ <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>
+ <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>
#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>
+
+</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");
+
+</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>
- 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>
-</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>
-
-
-<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");
+
+</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:
+ </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");
count = fscanf(FCGI_ToFile(myStream), format, ...);
- </pre>
-</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>
-<pre>
+
+</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://fastcgi.com">fastcgi.com</A> Web page for more information about the Perl and Tcl
+ libraries.
+ </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>
-
-<pre>
+</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>"
+ 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).
-
-
-
-<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>
-
-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>
-
-Here is the Java version of <tt>tiny-fcgi</tt>:<p>
-
-<pre>
+</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[]) {
+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.1">4.1 Using a Web server that supports FastCGI</a></h3>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-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>
-
-<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.
-</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>
-
-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:
-
-<pre>
+</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://fastcgi.com">fastcgi.com</A> Web page.
+ </P>
+ <P>
+ Some 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>
+ <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:
+ </P>
+ <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>
-
-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>
-
-
-
-<hr>
-
-<address>
-© 1996, Open Market, Inc. / mbrown@openmarket.com
-</address>
+</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</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, see <A HREF=
+ "http://fastcgi.com/fastcgi-developers">http://fastcgi.com/fastcgi-developers</A>.
+ </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>
-</body>
-</html>
projects / catagits/fcgi2.git / blobdiff