-<html><head><title>FastCGI Application Programmer's Guide - Index</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="apaman.htm">[Prev]</a> [Next] [Bottom]
-<hr><br>
-
-<a name="801">
-<center><h1> Index<br></h1></center>
-</a><a name="1384">
-<center><h2>A</h2></center>
-</a><dl>
-<a name="1388"></a>
-<dt><dd> <a href="ch4tcl.htm#4835">applications in Tcl 19</a>
-<a name="1390"></a>
-<dt><dd> <a href="ch1intro.htm#8428">Authorizer applications 4</a>
-<dl>
-<a name="1392"></a>
-<dt><dd> <a href="ch1intro.htm#9483">environment variables 6</a>
-<a name="1394"></a>
-<dt><dd> <a href="ch1intro.htm#8437">stdin and stderr 4</a>
-</dl>
-</dl>
-<a name="1396">
-<center><h2>C</h2></center>
-</a><dl>
-<a name="1399"></a>
-<dt><dd> <a href="ch2c.htm#917">C language, writing FastCGI applications in 11</a>
-</dl>
-<a name="1401">
-<center><h2>E</h2></center>
-</a><dl>
-<a name="1404"></a>
-<dt><dd> environment variables
-<dl>
-<a name="1405"></a>
-<dt><dd> <a href="ch1intro.htm#9483">differences from CGI 6</a>
-<a name="1407"></a>
-<dt><dd> <a href="ch1intro.htm#8431">returned from Authorizer applications 4</a>
-</dl>
-<a name="1409"></a>
-<dt><dd> examples
-<dl>
-<a name="1410"></a>
-<dt><dd> <a href="ch2c.htm#4182">responder application in C 13</a>
-<a name="1412"></a>
-<dt><dd> <a href="ch3perl.htm#5002">responder application in perl 18</a>
-<a name="1414"></a>
-<dt><dd> <a href="ch4tcl.htm#4343">responder application in Tcl 20</a>
-</dl>
-<a name="1416"></a>
-<dt><dd> <a href="apaman.htm#95796">exit status, of FastCGI application 24</a>
-</dl>
-<a name="1418">
-<center><h2>F</h2></center>
-</a><dl>
-<a name="1420"></a>
-<dt><dd> FastCGI
-<dl>
-<a name="1421"></a>
-<dt><dd> <a href="ch4tcl.htm#4835"> 19</a>
-<a name="1423"></a>
-<dt><dd> <a href="ch2c.htm#917">applications in C 11</a>
-<a name="1425"></a>
-<dt><dd> <a href="ch3perl.htm#917">applications in Perl 17</a>
-<a name="1427"></a>
-<dt><dd> <a href="ch1intro.htm#7995">differences from CGI 1</a>
-</dl>
-<a name="1429"></a>
-<dt><dd> <a href="apaman.htm#95732">FCGI_DATA_LAST_MOD 23</a>
-<a name="1431"></a>
-<dt><dd> <a href="apaman.htm#95731">FCGI_DATA_LENGTH 23</a>
-<a name="1433"></a>
-<dt><dd> <a href="ch1intro.htm#9488">FCGI_DATA_LENGTH (in Filter applications) 6</a>
-<a name="1435"></a>
-<dt><dd> <a href="ch1intro.htm#9490">FCGI_ROLE 6, </a><a href="apaman.htm#95661">22</a>
-<a name="1438"></a>
-<dt><dd> <a href="apaman.htm#95846">FCGI_SetExitStatus 24</a>
-<a name="1440"></a>
-<dt><dd> <a href="apaman.htm#95309">FCGI_StartFilterData 22</a>
-<a name="1442"></a>
-<dt><dd> <a href="ch2c.htm#4199">fcgi_stdio library 11</a>
-<dl>
-<a name="1444"></a>
-<dt><dd> <a href="ch2c.htm#4629">location of 15</a>
-<a name="1446"></a>
-<dt><dd> <a href="apaman.htm#95882">manpages for 21</a>
-</dl>
-<a name="1448"></a>
-<dt><dd> <a href="apaman.htm#95663">FCGI_ToFcgiStream 22</a>
-<a name="1450"></a>
-<dt><dd> <a href="apaman.htm#95663">FCGI_ToFILE 22</a>
-<a name="1452"></a>
-<dt><dd> <a href="ch2c.htm#4199">fcgiapp library 11</a>
-<a name="1454"></a>
-<dt><dd> <a href="ch1intro.htm#9486">FILE_LAST_MOD (in Filter applications) 6</a>
-<a name="1456"></a>
-<dt><dd> Filter applications
-<dl>
-<a name="1457"></a>
-<dt><dd> <a href="apaman.htm#95732">last modification time 23</a>
-<a name="1459"></a>
-<dt><dd> <a href="apaman.htm#95728">reading from stdin 23</a>
-</dl>
-</dl>
-<a name="1461">
-<center><h2>G</h2></center>
-</a><dl>
-<a name="1463"></a>
-<dt><dd> <a href="ch2c.htm#4785">Great Circle (C garbage collector) 16</a>
-</dl>
-<a name="1465">
-<center><h2>I</h2></center>
-</a><dl>
-<a name="1468"></a>
-<dt><dd> <a href="ch1intro.htm#9480">Initial Environment Variables 5</a>
-</dl>
-<a name="1470">
-<center><h2>M</h2></center>
-</a><dl>
-<a name="1475"></a>
-<dt><dd> <a href="apaman.htm#95882">manpages 21</a>
-<a name="1477"></a>
-<dt><dd> <a href="ch2c.htm#4190">memory leaks 16</a>
-</dl>
-<a name="1479">
-<center><h2>P</h2></center>
-</a><dl>
-<a name="1483"></a>
-<dt><dd> Perl
-<dl>
-<a name="1484"></a>
-<dt><dd> <a href="ch3perl.htm#917">writing FastCGI applications in 17</a>
-</dl>
-<a name="1486"></a>
-<dt><dd> <a href="ch2c.htm#4785">Purify (for checking storage leaks) 16</a>
-</dl>
-<a name="1488">
-<center><h2>R</h2></center>
-</a><dl>
-<a name="1491"></a>
-<dt><dd> <a href="ch1intro.htm#9477">response loop 5</a>
-<dl>
-<a name="1493"></a>
-<dt><dd> <a href="ch2c.htm#4202">in C 12</a>
-<a name="1495"></a>
-<dt><dd> <a href="ch3perl.htm#4243">in Perl 17</a>
-<a name="1497"></a>
-<dt><dd> <a href="ch4tcl.htm#4228">in TCL 19</a>
-</dl>
-</dl>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="apaman.htm">[Prev]</a> [Next] [Bottom]
-<hr><br>
-
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:22 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Application Programmer's Guide - Index\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="apaman.htm">[Prev]</A>\r
+ <P>\r
+ [Next] [Bottom]\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A NAME="801"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ Index<BR>\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="1384"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ A\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1388"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4835">applications in Tcl 19</A> <A NAME="1390"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8428">Authorizer applications 4</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1392"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9483">environment variables 6</A> <A NAME="1394"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8437">stdin and stderr 4</A>\r
+ </DD>\r
+ </DL>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1396"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ C\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1399"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#917">C language, writing FastCGI applications in 11</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1401"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ E\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1404"></A>\r
+ </DD>\r
+ <DD>\r
+ environment variables \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1405"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9483">differences from CGI 6</A> <A NAME="1407"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8431">returned from Authorizer applications 4</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1409"></A>\r
+ </DD>\r
+ <DD>\r
+ examples \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1410"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4182">responder application in C 13</A> <A NAME="1412"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#5002">responder application in perl 18</A> <A NAME="1414"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4343">responder application in Tcl 20</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1416"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95796">exit status, of FastCGI application 24</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1418"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ F\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1420"></A>\r
+ </DD>\r
+ <DD>\r
+ FastCGI \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1421"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4835">19</A> <A NAME="1423"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#917">applications in C 11</A> <A NAME="1425"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#917">applications in Perl 17</A> <A NAME="1427"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#7995">differences from CGI 1</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1429"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95732">FCGI_DATA_LAST_MOD 23</A> <A NAME="1431"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95731">FCGI_DATA_LENGTH 23</A> <A NAME="1433"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9488">FCGI_DATA_LENGTH (in Filter applications) 6</A> <A NAME="1435"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9490">FCGI_ROLE 6,</A> <A HREF="apaman.htm#95661">22</A> <A NAME="1438"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95846">FCGI_SetExitStatus 24</A> <A NAME="1440"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95309">FCGI_StartFilterData 22</A> <A NAME="1442"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4199">fcgi_stdio library 11</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1444"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4629">location of 15</A> <A NAME="1446"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95882">manpages for 21</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1448"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95663">FCGI_ToFcgiStream 22</A> <A NAME="1450"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95663">FCGI_ToFILE 22</A> <A NAME="1452"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4199">fcgiapp library 11</A> <A NAME="1454"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9486">FILE_LAST_MOD (in Filter applications) 6</A> <A NAME="1456"></A>\r
+ </DD>\r
+ <DD>\r
+ Filter applications \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1457"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95732">last modification time 23</A> <A NAME="1459"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95728">reading from stdin 23</A>\r
+ </DD>\r
+ </DL>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1461"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ G\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1463"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4785">Great Circle (C garbage collector) 16</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1465"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ I\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1468"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9480">Initial Environment Variables 5</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1470"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ M\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1475"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95882">manpages 21</A> <A NAME="1477"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4190">memory leaks 16</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1479"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ P\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1483"></A>\r
+ </DD>\r
+ <DD>\r
+ Perl \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1484"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#917">writing FastCGI applications in 17</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1486"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4785">Purify (for checking storage leaks) 16</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="1488"></A>\r
+ <DIV CLASS="c1">\r
+ <H2>\r
+ R\r
+ </H2>\r
+ </DIV>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="1491"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9477">response loop 5</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="1493"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4202">in C 12</A> <A NAME="1495"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#4243">in Perl 17</A> <A NAME="1497"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4228">in TCL 19</A>\r
+ </DD>\r
+ </DL>\r
+ </DD>\r
+ </DL>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="apaman.htm">[Prev]</A>\r
+ <P>\r
+ [Next] [Bottom]\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:22 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide - Table of Contents</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="cover.htm">[Prev]</a> <a href="ch1intro.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="4878">
-<h4>1. <a href="ch1intro.htm#9432">The Fast Common Gateway Interface 1</a></h4>
-</a><dl>
-<a name="4880"></a>
-<dt><dd> <a href="ch1intro.htm#8485">Advantages of FastCGI 1</a>
-<dl>
-<a name="4882"></a>
-<dt><dd> <a href="ch1intro.htm#8396">Long-lived Applications 1</a>
-<a name="4884"></a>
-<dt><dd> <a href="ch1intro.htm#8445">Separating Application and Server 2</a>
-<a name="4886"></a>
-<dt><dd> <a href="ch1intro.htm#8406">FastCGI "Roles" 2</a>
-</dl>
-<a name="4888"></a>
-<dt><dd> <a href="ch1intro.htm#4207">Writing FastCGI Applications 4</a>
-<dl>
-<a name="4890"></a>
-<dt><dd> <a href="ch1intro.htm#9469">Code Structure 5</a>
-<a name="4892"></a>
-<dt><dd> <a href="ch1intro.htm#9480">Initial Environment Variables 5</a>
-<a name="4894"></a>
-<dt><dd> <a href="ch1intro.htm#9785">Per-Request Environment Variables 6</a>
-<a name="4896"></a>
-<dt><dd> <a href="ch1intro.htm#9048">Building FastCGI Applications in C 6</a>
-<a name="4898"></a>
-<dt><dd> <a href="ch1intro.htm#9570">Building FastCGI Applications in Perl 7</a>
-<a name="4900"></a>
-<dt><dd> <a href="ch1intro.htm#9562">Building FastCGI Applications in Tcl 7</a>
-</dl>
-<a name="4902"></a>
-<dt><dd> <a href="ch1intro.htm#8360">Implementation Details 7</a>
-<dl>
-<a name="4904"></a>
-<dt><dd> <a href="ch1intro.htm#7874">The fcgi_stdio Library: I/O Compatibility 9</a>
-<a name="4906"></a>
-<dt><dd> <a href="ch1intro.htm#9678">The fcgi_stdio Library: Binary compatibility 10</a>
-</dl>
-</dl>
-<a name="4908">
-<h4>2. <a href="ch2c.htm#3659">Developing FastCGI Applications in C 11</a></h4>
-</a><dl>
-<a name="4910"></a>
-<dt><dd> <a href="ch2c.htm#5371">The I/O Libraries 11</a>
-<a name="4912"></a>
-<dt><dd> <a href="ch2c.htm#5847">Code Structure 12</a>
-<a name="4914"></a>
-<dt><dd> <a href="ch2c.htm#5373">Example 1: TinyFastCGI 12</a>
-<a name="4916"></a>
-<dt>
- <dd> <a href="ch2c.htm#4182">Example 2: Prime Number Generator 13</a>
- <a name="4918"></a>
-<dt><dd> <a href="ch2c.htm#5151">Building 15</a>
-<a name="4920"></a>
-<dt><dd> <a href="ch2c.htm#4190">Memory Leaks 16</a>
-</dl>
-<a name="4922">
-<h4>3. <a href="ch3perl.htm#3659">Developing FastCGI Applications in Perl 17</a></h4>
-</a><dl>
-<a name="4924"></a>
-<dt><dd> <a href="ch3perl.htm#4183">Getting Started 17</a>
-<a name="4926"></a>
-<dt><dd> <a href="ch3perl.htm#5002">Example: TinyFastCGI 18</a>
-</dl>
-<a name="4928">
-<h4>4. <a href="ch4tcl.htm#3659">Developing FastCGI Applications in Tcl 19</a></h4>
-</a><dl>
-<a name="4930"></a>
-<dt><dd> <a href="ch4tcl.htm#4222">Getting Started 19</a>
-<a name="4932"></a>
-<dt><dd> <a href="ch4tcl.htm#4853">Example: TinyFastCGI 20</a>
-</dl>
-<a name="4934">
-<h4>A. <a href="apaman.htm#3601">FastCGI Reference Pages 21</a></h4>
-</a><dl>
-<a name="4936"></a>
-<dt><dd> <a href="apaman.htm#95860">FCGI_Accept (3) 21</a>
-<dl>
-<a name="4938"></a>
-<dt><dd> <a href="apaman.htm#95861">Name 21</a>
-<a name="4940"></a>
-<dt><dd> <a href="apaman.htm#95652">Synopsis 21</a>
-<a name="4942"></a>
-<dt><dd> <a href="apaman.htm#95656">Description 21</a>
-<a name="4944"></a>
-<dt><dd> <a href="apaman.htm#95664">Return Values 22</a>
-</dl>
-<a name="4946"></a>
-<dt><dd> <a href="apaman.htm#95309">FCGI_StartFilterData (3) 22</a>
-<dl>
-<a name="4948"></a>
-<dt><dd> <a href="apaman.htm#95310">Name 22</a>
-<a name="4950"></a>
-<dt><dd> <a href="apaman.htm#95312">Synopsis 22</a>
-<a name="4952"></a>
-<dt><dd> <a href="apaman.htm#95315">Description 23</a>
-<a name="4954"></a>
-<dt><dd> <a href="apaman.htm#95733">Return Values 23</a>
-<a name="4956"></a>
-<dt><dd> <a href="apaman.htm#95323">Example 23</a>
-</dl>
-<a name="4958"></a>
-<dt><dd> <a href="apaman.htm#95846">FCGI_SetExitStatus(3) 24</a>
-<dl>
-<a name="4960"></a>
-<dt><dd> <a href="apaman.htm#95793">Name 24</a>
-<a name="4962"></a>
-<dt><dd> <a href="apaman.htm#95786">Synopsis 24</a>
-<a name="4964"></a>
-<dt><dd> <a href="apaman.htm#95788">Description 24</a>
-</dl>
-</dl>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="cover.htm">[Prev]</a> <a href="ch1intro.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:12 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide - Table of Contents\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="cover.htm">[Prev]</A> <A HREF="ch1intro.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ \r
+ <H4>\r
+ 1. <A HREF="ch1intro.htm#9432">The Fast Common Gateway Interface 1</A>\r
+ </H4>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="4880"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8485">Advantages of FastCGI 1</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4882"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8396">Long-lived Applications 1</A> <A NAME="4884"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8445">Separating Application and Server 2</A> <A NAME="4886"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8406">FastCGI "Roles" 2</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="4888"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#4207">Writing FastCGI Applications 4</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4890"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9469">Code Structure 5</A> <A NAME="4892"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9480">Initial Environment Variables 5</A> <A NAME="4894"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9785">Per-Request Environment Variables 6</A> <A NAME="4896"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9048">Building FastCGI Applications in C 6</A> <A NAME="4898"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9570">Building FastCGI Applications in Perl 7</A> <A NAME="4900"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9562">Building FastCGI Applications in Tcl 7</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="4902"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#8360">Implementation Details 7</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4904"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#7874">The fcgi_stdio Library: I/O Compatibility 9</A> <A NAME="4906"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch1intro.htm#9678">The fcgi_stdio Library: Binary compatibility 10</A>\r
+ </DD>\r
+ </DL>\r
+ </DD>\r
+ </DL>\r
+ <H4>\r
+ 2. <A HREF="ch2c.htm#3659">Developing FastCGI Applications in C 11</A>\r
+ </H4>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="4910"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#5371">The I/O Libraries 11</A> <A NAME="4912"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#5847">Code Structure 12</A> <A NAME="4914"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#5373">Example 1: TinyFastCGI 12</A> <A NAME="4916"></A>\r
+ </DD>\r
+ <DT>\r
+ </DT>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4182">Example 2: Prime Number Generator 13</A> <A NAME="4918"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#5151">Building 15</A> <A NAME="4920"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch2c.htm#4190">Memory Leaks 16</A>\r
+ </DD>\r
+ </DL>\r
+ <H4>\r
+ 3. <A HREF="ch3perl.htm#3659">Developing FastCGI Applications in Perl 17</A>\r
+ </H4>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="4924"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#4183">Getting Started 17</A> <A NAME="4926"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch3perl.htm#5002">Example: TinyFastCGI 18</A>\r
+ </DD>\r
+ </DL>\r
+ <H4>\r
+ 4. <A HREF="ch4tcl.htm#3659">Developing FastCGI Applications in Tcl 19</A>\r
+ </H4>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="4930"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4222">Getting Started 19</A> <A NAME="4932"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="ch4tcl.htm#4853">Example: TinyFastCGI 20</A>\r
+ </DD>\r
+ </DL>\r
+ <H4>\r
+ A. <A HREF="apaman.htm#3601">FastCGI Reference Pages 21</A>\r
+ </H4>\r
+ <DL>\r
+ <DD>\r
+ <A NAME="4936"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95860">FCGI_Accept (3) 21</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4938"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95861">Name 21</A> <A NAME="4940"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95652">Synopsis 21</A> <A NAME="4942"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95656">Description 21</A> <A NAME="4944"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95664">Return Values 22</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="4946"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95309">FCGI_StartFilterData (3) 22</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4948"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95310">Name 22</A> <A NAME="4950"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95312">Synopsis 22</A> <A NAME="4952"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95315">Description 23</A> <A NAME="4954"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95733">Return Values 23</A> <A NAME="4956"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95323">Example 23</A>\r
+ </DD>\r
+ </DL>\r
+ <A NAME="4958"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95846">FCGI_SetExitStatus(3) 24</A> \r
+ <DL>\r
+ <DD>\r
+ <A NAME="4960"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95793">Name 24</A> <A NAME="4962"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95786">Synopsis 24</A> <A NAME="4964"></A>\r
+ </DD>\r
+ <DD>\r
+ <A HREF="apaman.htm#95788">Description 24</A>\r
+ </DD>\r
+ </DL>\r
+ </DD>\r
+ </DL>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="cover.htm">[Prev]</A> <A HREF="ch1intro.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:12 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FCGI_Accept(2) Man Page</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="ch4tcl.htm">[Prev]</a> <a href="ap_guida.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="3601">
-<center><h1>A FastCGI <br>Reference Pages</h1></center>
-</a><a name="95882"></a>
-This appendix contains reference pages for the following FastCGI routines from the <code>fcgi_stdio</code> library:<p>
-<ul><a name="95884"></a>
-<li><code>FCGI_Accept</code>
-<a name="95885"></a>
-<li><code>FCGI_Start_Filter_Data</code>
-<a name="95859"></a>
-<li><code>FCGI_SetExitStatus</code>
-</ul><a name="95860">
-<h1> FCGI_Accept (3)</h1>
-</a><a name="95861">
-<h2> Name</h2>
-</a><a name="95637"></a>
-<code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p>
-<a name="95652">
-<h2> Synopsis</h2>
-</a><pre><a name="95669">
-#include <fcgi_stdio.h>
-</a>
-<a name="95653">
-int <br>FCGI_Accept(void);
-</a>
-<a name="95654">
-FILE * <br>FCGI_ToFILE(FCGI_FILE *);
-</a>
-<a name="95655">
-FCGI_Stream * <br>FCGI_ToFcgiStream(FCGI_FILE *);
-</a>
-</pre><a name="95656">
-<h2> Description </h2>
-</a><a name="95683"></a>
-The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution environment for the request.<p>
-<a name="95657"></a>
-If the application was invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a single request and exit, giving CGI behavior.<p>
-<a name="95658"></a>
-If the application was invoked as a FastCGI server, the first call to FCGI_Accept indicates that the application has completed its initialization and is ready to accept its first request. Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and is ready to accept a new request.<p>
-<a name="95659"></a>
-In completing the current request, FCGI_Accept may detect errors, such as a broken pipe to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one indicates an error.<p>
-<a name="95660"></a>
-After accepting a new request, FCGI_Accept assigns new values to the global variables stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as on entry to a CGI program.<p>
-<a name="95661"></a>
-In addition to the standard CGI environment variables, the environment variable <code>FCGI_ROLE</code> is always set to the role of the current request. The roles currently defined are <code>RESPONDER, AUTHORIZER</code>, and <code>FILTER</code>.<p>
-<a name="95662"></a>
-In the <code>FILTER</code> role, the additional variables <code>FCGI_DATA_LENGTH</code> and <code>FCGI_DATA_LAST_MOD</code> are also defined. See <code>FCGI_StartFilterData</code><code>(3</code>) for complete information.<p>
-<a name="95663"></a>
-The macros <code>FCGI_ToFILE</code> and <code>FCGI_ToFcgiStream</code> are provided to allow escape to native functions that use the types <code>FILE</code> or <code>FCGI_Stream</code>. In the case of <code>FILE</code>, functions would have to be separately compiled, since <code>fcgi_stdio.h</code> replaces the standard <code>FILE</code> with <code>FCGI_FILE</code>.<p>
-<a name="95664">
-<h2> Return Values</h2>
-</a><a name="95686"></a>
-0 for successful call, -1 for error (application should exit).<p>
-<a name="95309">
-<h1> FCGI_StartFilterData (3)</h1>
-</a><a name="95310">
-<h2> Name</h2>
-</a><a name="95311"></a>
-<code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p>
-<a name="95312">
-<h2> Synopsis</h2>
-</a><pre><a name="95313">
-#include <fcgi_stdio.h>
-</a>
-<a name="95314">
-int FCGI_StartFilterData(void)
-</a>
-</pre><a name="95315">
-<h2> Description</h2>
-</a><a name="95728"></a>
-Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<p>
-<a name="95729"></a>
-In order to call <code>FCGI_StartFilterData</code>, the FastCGI application should have been invoked in the filter role (<code>getenv("FCGI_ROLE") == "FILTER"</code>), and should have read <code>stdin</code> to EOF, consuming the entire <code>FCGI_STDIN</code> data stream. The call to <code>FCGI_StartFilterData</code> positions stdin at the start of <code>FCGI_DATA</code>.<p>
-<a name="95730"></a>
-If the preconditions are not met (e.g., the application has not read <code>stdin</code> to EOF), <code>FCGI_StartFilterData</code> returns a negative result, and the application will get EOF on attempts to read from <code>stdin</code>.<p>
-<a name="95731"></a>
-The application can determine the number of bytes available on <code>FCGI_DATA</code> by performing <code>atoi(getenv("FCGI_DATA_LENGTH")</code>. If fewer than this many bytes are delivered on <code>stdin</code> after calling <code>FCGI_StartFilterData</code>, the application should perform an application-specific error response. If the application normally makes an update, most likely it should abort the update.<p>
-<a name="95732"></a>
-The application can determine last modification time of the filter input data by performing <code>getenv("FCGI_DATA_LAST_MOD").</code> This allows applications to perform caching based on last modification time.<p>
-<a name="95733">
-<h2> Return Values</h2>
-</a><a name="95322"></a>
-Returns 0 on success and a negative integer on failure. <p>
-<a name="95323">
-<h2> Example</h2>
-</a><a name="95363"></a>
-The following example reads in all the client data, but ignores it. Then, the code calls <code>FCGI_StartFilterData</code>. Finally, the code reads in the file to be filtered and simply echos it back to the client. <p>
-<pre><a name="95324">
-while (FCGI_Accept() >= 0) {
-</a>
-<a name="95325">
-...
-</a>
-<a name="95364">
- /* Read data passed by client. */
-</a>
-<a name="95358">
- while (getchar () != OF)
-</a>
-<a name="95935">
-{
-</a>
-<a name="95930">
-}
-</a>
-<a name="95359">
-
-</a>
-<a name="95367">
- /* Adjust standard input stream. */
-</a>
-<a name="95366">
- status = FCGI_StartFilterData();
-</a>
-<a name="95369">
-
-</a>
-<a name="95360">
- /* Read in filter data and echo it back to client. */
-</a>
-<a name="95368">
- while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0)
-</a>
-<a name="95361">
- fwrite(tempBuffer, 1, len, stdout);
-</a>
-<a name="95844">
-
-</a>
-<a name="95845">
-} /* End FCGI_Accept loop */
-</a>
-</pre><a name="95846">
-<h1> FCGI_SetExitStatus(3)</h1>
-</a><a name="95793">
-<h2> Name </h2>
-</a><a name="95794"></a>
-<code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p>
-<a name="95786">
-<h2> Synopsis </h2>
-</a><pre><a name="95795">
-#include <fcgi_stdio.h>
-</a>
-<a name="95787">
-void FCGI_SetExitStatus(int status);
-</a>
-</pre><a name="95788">
-<h2> Description </h2>
-</a><a name="95796"></a>
-Sets the exit status for the current FastCGI request. The exit status is the status code the request would have exited with, had the request been run as a CGI program.<p>
-<a name="95789"></a>
-You can call <code>FCGI_SetExitStatus</code> several times during a request; the last call before the request ends determines the value.<p>
-<a name="95797"></a>
-<p>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="ch4tcl.htm">[Prev]</a> <a href="ap_guida.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:20 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FCGI_Accept(2) Man Page\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ li.c2 {list-style: none}\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <A NAME="3601"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ A FastCGI<BR>\r
+ Reference Pages\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="95882"></A>\r
+ <P>\r
+ This appendix contains reference pages for the following FastCGI routines from the <CODE>fcgi_stdio</CODE>\r
+ library:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="95884"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>FCGI_Accept</CODE> <A NAME="95885"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>FCGI_Start_Filter_Data</CODE> <A NAME="95859"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>FCGI_SetExitStatus</CODE>\r
+ </LI>\r
+ </UL>\r
+ <H1>\r
+ FCGI_Accept (3)\r
+ </H1>\r
+ <H2>\r
+ Name\r
+ </H2>\r
+ <A NAME="95637"></A> <CODE>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</CODE>\r
+ <P>\r
+ - fcgi_stdio compatibility library\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Synopsis\r
+ </H2>\r
+<PRE>\r
+<A NAME="95669">#include <fcgi_stdio.h>\r
+</A>\r
+<A NAME="95653">int<BR>\r
+ FCGI_Accept(void);\r
+</A>\r
+<A NAME="95654">FILE *<BR>\r
+ FCGI_ToFILE(FCGI_FILE *);\r
+</A>\r
+<A NAME="95655">FCGI_Stream *<BR>\r
+ FCGI_ToFcgiStream(FCGI_FILE *);\r
+</A>\r
+</PRE>\r
+ <H2>\r
+ Description\r
+ </H2>\r
+ <A NAME="95683"></A>\r
+ <P>\r
+ The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution\r
+ environment for the request.\r
+ </P>\r
+ <P>\r
+ <A NAME="95657"></A> If the application was invoked as a CGI program, the first call to FCGI_Accept is\r
+ essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a\r
+ single request and exit, giving CGI behavior.\r
+ </P>\r
+ <P>\r
+ <A NAME="95658"></A> If the application was invoked as a FastCGI server, the first call to FCGI_Accept\r
+ indicates that the application has completed its initialization and is ready to accept its first request.\r
+ Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and\r
+ is ready to accept a new request.\r
+ </P>\r
+ <P>\r
+ <A NAME="95659"></A> In completing the current request, FCGI_Accept may detect errors, such as a broken pipe\r
+ to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle\r
+ such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one\r
+ indicates an error.\r
+ </P>\r
+ <P>\r
+ <A NAME="95660"></A> After accepting a new request, FCGI_Accept assigns new values to the global variables\r
+ stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as\r
+ on entry to a CGI program.\r
+ </P>\r
+ <P>\r
+ <A NAME="95661"></A> In addition to the standard CGI environment variables, the environment variable\r
+ <CODE>FCGI_ROLE</CODE> is always set to the role of the current request. The roles currently defined are\r
+ <CODE>RESPONDER, AUTHORIZER</CODE>, and <CODE>FILTER</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="95662"></A> In the <CODE>FILTER</CODE> role, the additional variables <CODE>FCGI_DATA_LENGTH</CODE>\r
+ and <CODE>FCGI_DATA_LAST_MOD</CODE> are also defined. See <CODE>FCGI_StartFilterData</CODE><CODE>(3</CODE>)\r
+ for complete information.\r
+ </P>\r
+ <P>\r
+ <A NAME="95663"></A> The macros <CODE>FCGI_ToFILE</CODE> and <CODE>FCGI_ToFcgiStream</CODE> are provided to\r
+ allow escape to native functions that use the types <CODE>FILE</CODE> or <CODE>FCGI_Stream</CODE>. In the case\r
+ of <CODE>FILE</CODE>, functions would have to be separately compiled, since <CODE>fcgi_stdio.h</CODE> replaces\r
+ the standard <CODE>FILE</CODE> with <CODE>FCGI_FILE</CODE>.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Return Values\r
+ </H2>\r
+ <A NAME="95686"></A>\r
+ <P>\r
+ 0 for successful call, -1 for error (application should exit).\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ FCGI_StartFilterData (3)\r
+ </H1>\r
+ <H2>\r
+ Name\r
+ </H2>\r
+ <A NAME="95311"></A> <CODE>FCGI_StartFilterData</CODE>\r
+ <P>\r
+ -<CODE>fcgi_stdio</CODE> compatibility library\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Synopsis\r
+ </H2>\r
+<PRE>\r
+<A NAME="95313">#include <fcgi_stdio.h>\r
+</A>\r
+<A NAME="95314">int FCGI_StartFilterData(void)\r
+</A>\r
+</PRE>\r
+ <H2>\r
+ Description\r
+ </H2>\r
+ <A NAME="95728"></A>\r
+ <P>\r
+ Enables a FastCGI Filter application to begin reading its filter input data from <CODE>stdin</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="95729"></A> In order to call <CODE>FCGI_StartFilterData</CODE>, the FastCGI application should have\r
+ been invoked in the filter role (<CODE>getenv("FCGI_ROLE") == "FILTER"</CODE>), and should\r
+ have read <CODE>stdin</CODE> to EOF, consuming the entire <CODE>FCGI_STDIN</CODE> data stream. The call to\r
+ <CODE>FCGI_StartFilterData</CODE> positions stdin at the start of <CODE>FCGI_DATA</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="95730"></A> If the preconditions are not met (e.g., the application has not read <CODE>stdin</CODE>\r
+ to EOF), <CODE>FCGI_StartFilterData</CODE> returns a negative result, and the application will get EOF on\r
+ attempts to read from <CODE>stdin</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="95731"></A> The application can determine the number of bytes available on <CODE>FCGI_DATA</CODE> by\r
+ performing <CODE>atoi(getenv("FCGI_DATA_LENGTH")</CODE>. If fewer than this many bytes are delivered\r
+ on <CODE>stdin</CODE> after calling <CODE>FCGI_StartFilterData</CODE>, the application should perform an\r
+ application-specific error response. If the application normally makes an update, most likely it should abort\r
+ the update.\r
+ </P>\r
+ <P>\r
+ <A NAME="95732"></A> The application can determine last modification time of the filter input data by\r
+ performing <CODE>getenv("FCGI_DATA_LAST_MOD").</CODE> This allows applications to perform caching\r
+ based on last modification time.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Return Values\r
+ </H2>\r
+ <A NAME="95322"></A>\r
+ <P>\r
+ Returns 0 on success and a negative integer on failure.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Example\r
+ </H2>\r
+ <A NAME="95363"></A>\r
+ <P>\r
+ The following example reads in all the client data, but ignores it. Then, the code calls\r
+ <CODE>FCGI_StartFilterData</CODE>. Finally, the code reads in the file to be filtered and simply echos it back\r
+ to the client.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="95324">while (FCGI_Accept() >= 0) {\r
+</A>\r
+<A NAME="95325">...\r
+</A>\r
+ <A NAME="95364">/* Read data passed by client. */\r
+</A>\r
+ <A NAME="95358"> while (getchar () != OF) \r
+</A>\r
+<A NAME="95935">{\r
+</A>\r
+<A NAME="95930">}\r
+</A>\r
+<A NAME="95359">\r
+</A>\r
+ <A NAME="95367">/* Adjust standard input stream. */\r
+</A>\r
+ <A NAME="95366"> status = FCGI_StartFilterData();\r
+</A>\r
+<A NAME="95369">\r
+</A>\r
+ <A NAME="95360">/* Read in filter data and echo it back to client. */\r
+</A>\r
+ <A NAME="95368"> while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0) \r
+</A>\r
+ <A NAME="95361"> fwrite(tempBuffer, 1, len, stdout);\r
+</A>\r
+<A NAME="95844">\r
+</A>\r
+<A NAME="95845">} /* End FCGI_Accept loop */\r
+</A>\r
+</PRE>\r
+ <H1>\r
+ FCGI_SetExitStatus(3)\r
+ </H1>\r
+ <H2>\r
+ Name\r
+ </H2>\r
+ <A NAME="95794"></A> <CODE>FCGI_SetExitStatus</CODE>\r
+ <P>\r
+ - <CODE>fcgi_stdio</CODE> compatibility library\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Synopsis\r
+ </H2>\r
+<PRE>\r
+<A NAME="95795">#include <fcgi_stdio.h>\r
+</A>\r
+<A NAME="95787">void FCGI_SetExitStatus(int status);\r
+</A>\r
+</PRE>\r
+ <H2>\r
+ Description\r
+ </H2>\r
+ <A NAME="95796"></A>\r
+ <P>\r
+ Sets the exit status for the current FastCGI request. The exit status is the status code the request would\r
+ have exited with, had the request been run as a CGI program.\r
+ </P>\r
+ <P>\r
+ <A NAME="95789"></A> You can call <CODE>FCGI_SetExitStatus</CODE> several times during a request; the last\r
+ call before the request ends determines the value.\r
+ </P>\r
+ <P>\r
+ <A NAME="95797"></A>\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:20 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide - Chapter 1, The Fast Common Gateway Interface</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="ap_guide.htm">[Prev]</a> <a href="ch2c.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="9432">
-<center><h1>1 The Fast Common<br>Gateway Interface</h1></center>
-</a><a name="7982"></a>
-The Fast Common Gateway Interface (FastCGI) is an enhancement to the existing CGI (Common Gateway Interface), which is a standard for interfacing external applications with Web servers. <p>
-<a name="8373"></a>
-FastCGI is a proposed open standard and we expect both free and commercial Web servers to support it. FastCGI is included in Open Market WebServer and Secure WebServer, versions 2.0 and greater.<p>
-<a name="8485">
-<h1> Advantages of FastCGI</h1>
-</a><a name="8369"></a>
-FastCGI extends and enhances the CGI model in several ways:<p>
-<ul><a name="7832"></a>
-<li>FastCGI enables applications to persist between client requests, eliminating application start up overhead and allowing the application to maintain state between client calls.
-<a name="7995"></a>
-<li>FastCGI enables applications to reside on remote systems (rather than having to reside on the same system as the Web server)
-<a name="7997"></a>
-<li>FastCGI enables additional flexibility in application functionality, with explicit support for applications that do client authentication and filtering of input.
-</ul><a name="8396">
-<h2> Long-lived Applications</h2>
-</a><a name="8458"></a>
-CGI applications are ephemeral and short-lived: each time a client requests a CGI application, the server asks the operating system to spawn a new CGI process. After the CGI process satisfies the request, the server kills it. The server spawns and subsequently kills a new process for each client request. <p>
-<a name="8459"></a>
-FastCGI applications are long-lived, and can persist between client calls. The server spawns the FastCGI process once and it continues to run and satisfy client requests until it is explicitly terminated. You can also ask the Web server to start multiple copies of a FastCGI application, if you expect that concurrent processing will improve the application's performance. <p>
-<a name="5761"></a>
-Long-lived applications have two important advantages over short-lived applications:<p>
-<ul><a name="7138"></a>
-<li>A short-lived application pays start up overhead on every request; a long-lived application spreads the overhead over many requests. For an application that has a heavy start up cost, such as opening a database, doing initialization on every call can be very inefficient. Reinitializing for every client is also very inefficient for Perl programs, where the interpreter reads through the entire program before executing any of it.
-<a name="9204"></a>
-<li>A long-lived application can cache information in memory between requests, allowing it to respond more quickly to later requests.
-</ul><a name="8733"></a>
-FastCGI is not the only way to get a long-lived application on the Web, however. For example, there are many existing search engines that are implemented as long-lived applications.<p>
-<a name="8734"></a>
-In most cases, these applications rely on customized Web servers. In other words, since most Web servers do not support long-lived applications, a programmer must code this support into a Web server. This approach requires a tremendous amount of work and also ties the application to a particular server.<p>
-<a name="8735"></a>
-Another way to get a long-lived application is to write code that calls routines from the Web server's API. This alternative involves a lot of extra coding, ties the application to a particular Web server, and introduces problems of maintainability, scalability, and security.<p>
-<a name="8736"></a>
-We believe that FastCGI is the most general and flexible strategy for building long-lived Web applications.<p>
-<a name="8445">
-<h2> Separating Application and Server</h2>
-</a><a name="8446"></a>
-CGI applications must run on the same node as the Web server; FastCGI applications can run on any node that can be reached from your Web server using TCP/IP protocols. For example, you might want to run the FastCGI application on a high-speed computer server or database engine, and run the Web server on a different node.<p>
-<a name="8406">
-<h2> FastCGI "Roles"</h2>
-</a><a name="8777"></a>
-CGI and FastCGI applications are effective ways to allow an application to act as an extension to the Web server. CGI provides no explicit support for different kinds of applications: under CGI, every application receives an HTTP request, does something with it, and generates an HTTP response. FastCGI provides explicit support for several common "roles" that applications can play. <p>
-<a name="8769"></a>
-The three roles supported by the WebServer 2.0 are: <p>
-<ul><a name="8409"></a>
-<li>Responder
-<a name="8410"></a>
-<li>Filter
-<a name="8411"></a>
-<li>Authorizer
-</ul><a name="8412">
-<h3> Responder Applications</h3>
-</a><a name="8679"></a>
-A <em>responder</em> application is the most basic kind of FastCGI application: it receives the information associated with an HTTP request and generates an HTTP response. Responder is the role most similar to traditional CGI programming, and most FastCGI applications are responders.<p>
-<a name="8680">
-<h3> Filter Applications</h3>
-</a><a name="8681"></a>
-A <em>filter</em> FastCGI application receives the information associated with an HTTP request, plus an extra stream of data from a file stored on the Web server, and generates a "filtered" version of the data stream as an HTTP response. <p>
-<a name="8421"></a>
-With filter applications, the system administrator maps a particular MIME-type to a particular filter FastCGI application. When a client requests a URL with that MIME-type, the Web server invokes the filter application, which processes the file at the specified URL and sends a response (usually HTML text) back to the client.<p>
-<a name="8422"></a>
-For example, suppose you write a filter FastCGI application that converts SGML text to HTML, and map the extension .sgml (MIME-type SGML) to your filter FastCGI application. Now, suppose that a user requests the following URL:<p>
-<pre><a name="8423">
-/www.aerjug.com/docs/chap1.sgml
-</a>
-</pre><a name="8424"></a>
-Given this URL, the Web server passes <code>chap1.sgml</code> as input to your filter FastCGI application, which processes <code>chap1.sgml</code> and returns an HTML version of it to the requesting client.<p>
-<a name="8425">
-<h3> Authorizer Applications</h3>
-</a><a name="8426"></a>
-An <em>authorizer</em> FastCGI application receives the information in an HTTP request header and generates a decision whether to authorize the request.<p>
-<a name="8428"></a>
-To mark a FastCGI application as having the authorizer role, the system administrator names the application inside the server configuration file, using a directive called <code>AuthorizeRegion</code>. (See the Open Market Web Server manual for information on server configuration directives.)<p>
-<a name="8429"></a>
-When a client requests a URL that meets the <code>AuthorizeRegion </code>criteria, the Web server calls your authorizer FastCGI application. If your application grants authorization (by returning a response code of 200), the Web server resumes execution of commands in the <code>AuthorizeRegion</code> section. If your application denies authorization (by returning any other response code), the Web server stops processing subsequent commands in the <code>AuthorizeRegion</code> section, and returns the response from your FastCGI application to the client.<p>
-<a name="8431"></a>
-Authorizer applications can return headers containing environment variables. Other CGI or FastCGI programs accessing this request (including other authorizers) can access these environment variables. The headers must have the following format:<p>
-<pre><a name="8432">
-Variable-<em>name</em>: <em>value</em>
-</a>
-</pre><a name="8433"></a>
-For example, the following header<p>
-<pre><a name="8434">
-Variable-AUTH_METHOD: database lookup
-</a>
-</pre><a name="8435"></a>
-causes the environment variable <code>AUTH_METHOD</code> to be set to <code>"database lookup"</code> for this request. Other CGI or FastCGI applications running on this request can access the value of <code>AUTH_METHOD</code>. <p>
-<a name="8437"></a>
-Authorizer applications cannot successfully read from standard input. Any attempts to read from standard input result in an immediate EOF.<p>
-<a name="8438"></a>
-All data that authorizer applications write to standard error will get written to the traditional server error logs. <p>
-<a name="4207">
-<h1> Writing FastCGI Applications</h1>
-</a><a name="9301"></a>
-The work involved in writing a FastCGI application depends in large part on the I/O libraries that you use. This manual describes how to write FastCGI applications in terms of the Open Market libraries, which are available for C, Perl, and Tcl. FastCGI is an open standard and you are welcome to build your own libraries for other languages as well, but this manual focuses on building FastCGI applications in the context of the Open Market libraries.<p>
-<a name="9443"></a>
-<p>
-<a name="9450"></a>
-In general, the goal of the libraries is to make the job of writing a FastCGI application as much like writing a CGI application as possible. For example, you use the same techniques for query string decoding, HTML output to stdout, use of environment variables, and so on. When you use our libraries, porting CGI applications to FastCGI is mostly a matter of restructuring the code to take advantage of FastCGI features and libraries. <p>
-<a name="9469">
-<h2> Code Structure</h2>
-</a><a name="9470"></a>
-The main task of converting a CGI program into a FastCGI program is separating the initialization code from the code that needs to run for each request. The structure should look something like this:<p>
-<pre><a name="9471">
-Initialization code
-</a>
-<a name="9472">
-Start of response loop
-</a>
-<a name="9473">
- body of response loop
-</a>
-<a name="9474">
-End of response loop
-</a>
-</pre><a name="9475"></a>
-The <em>initialization code</em> is run exactly once, when the application is initialized. Initialization code usually performs time-consuming operations such as opening databases or calculating values for tables or bitmaps. <p>
-<a name="9477"></a>
-The <em>response loop</em> runs continuously, waiting for client requests to arrive. The loop starts with a call to <code>FCGI_Accept</code>, a routine in the FastCGI library. The <code>FCGI_Accept</code> routine blocks program execution until a client requests the FastCGI application. When a client request comes in, <code>FCGI_Accept</code> unblocks, runs one iteration of the response loop body, and then blocks again waiting for another client request. The loop terminates only when the system administrator or the Web server kills the FastCGI application.<p>
-<a name="9480">
-<h2> Initial Environment Variables</h2>
-</a><a name="9786"></a>
-When a FastCGI process starts up, it has not yet accepted a request, and therefore none of the CGI environment variables are set.<p>
-<a name="9787"></a>
-You set the initial environment of a FastCGI process started by the <code>AppClass </code>directive using the <code>-initial-env</code> option. The process would use this environment to configure its options and locate files or databases.<p>
-<a name="9829"></a>
-In FastCGI processes started by the <code>AppClass</code> directive with the -affinity option, the <code>FCGI_PROCESS_ID</code> variable is set in the initial environment (not in the environment of a request). <code>FCGI_PROCESS_ID</code> is a decimal number in the range 0 to N - 1 where N is the number of processes (argument to the<code> -processes</code> option to <code>AppClass</code>). The process would use <code>FCGI_PROCESS_ID </code>in conjunction with other variables to locate session-related files or databases during restart.<p>
-<a name="9785">
-<h2> Per-Request Environment Variables</h2>
-</a><a name="9481"></a>
-In general, FastCGI uses the same per-request environment variables as CGI, and you access the values of environment variables in FastCGI applications just as you would in CGI applications. The only differences are as follows:<p>
-<ul><a name="9483"></a>
-<li>In Authorizer FastCGI applications, the Web server unsets the <code>PATH_INFO</code>, <code>PATH_TRANSLATED</code>, and <code>CONTENT_LENGTH</code> variables.
-<a name="9484"></a>
-<li>In Filter FastCGI applications, the Web server sets two additional environment variables:
-<ul>
-<a name="9486"></a>
-<li><code>FILE_LAST_MOD</code>: The Web server sets <code>FILE_LAST_MOD</code> to the date and time that filter input file was last modified. The format is the number of seconds since midnight (UTC), January 1, 1970.
-<a name="9488"></a>
-<li><code>FCGI_DATA_LENGTH</code>: The application reads at most <code>FCGI_DATA_LENGTH</code> bytes from the data stream before receiving the end-of-stream indication.
-</ul>
-<a name="9490"></a>
-<li>FastCGI sets <code>FCGI_ROLE</code> for each request to <code>RESPONDER</code>, <code>AUTHORIZER</code>, or <code>FILTER</code>.
-</ul><a name="9048">
-<h2> Building FastCGI Applications in C</h2>
-</a><a name="9049"></a>
-The Software Development Toolkit that accompanies WebServer 2.0 contains two libraries, fcgi_stdio and fcgiapp, for building FastCGI applications in C. <p>
-<a name="9723"></a>
-The fcgi_stdio library implements our philosophy of making FastCGI applications similar to CGI applications, and provides full binary compatibility between FastCGI applications and CGI applications: you can run the same C binary as either CGI or FastCGI. <p>
-<a name="9545"></a>
-The fcgiapp library is more specific to FastCGI, and doesn't attempt the veneer of CGI. <p>
-<a name="9731"></a>
-We recommend that you use the fcgi_stdio library, and this manual describes the routines in that library. The documentation for the fcgiapp library is in the code in the development kit.<p>
-<a name="9570">
-<h2> Building FastCGI Applications in Perl</h2>
-</a><a name="9581"></a>
-To build FastCGI applications in Perl, you need a FastCGI-savvy version of Perl, plus the FastCGI extension to Perl. We build FastCGI-savvy versions of the Perl interpreter for several common platforms and make them available on our Website. For details and examples, see Chapter <a href="ch3perl.htm#3659">3, "Developing FastCGI Applications in Perl," on page 17</a>.<p>
-<a name="9562">
-<h2> Building FastCGI Applications in Tcl</h2>
-</a><a name="9586"></a>
-To build FastCGI applications in Tcl, you need a FastCGI-savvy version of Tcl. We build FastCGI-savvy versions of the Tcl interpreter for several common platforms and make them available on our Website. For details and examples, see Chapter <a href="ch4tcl.htm#3659">4, "Developing FastCGI Applications in Tcl," on page 19</a>.<p>
-<a name="8360">
-<h1> Implementation Details</h1>
-</a><a name="8066"></a>
-The FastCGI application libraries are designed to shield you from the details of the FastCGI design. This section is designed for the curious reader who would like some low-level understanding. If you are not curious about the implementation, you can happily skip this section.<p>
-<a name="8554"></a>
-As shown in the following figure, CGI applications use the three standard POSIX streams (<code>stdin</code>, <code>stdout</code>, and <code>stderr</code>), plus environment variables, to communicate with an HTTP server. <p>
-<a name="8359"></a>
-<img src="ch1intra.gif"><p>
-<a name="4295"></a>
-<p>
-<a name="8575">
-<h5>Figure 1:  Flow of Data in CGI</h5>
-</a><a name="9001"></a>
-The fundamental difference between FastCGI and CGI is that FastCGI applications are long-lived, which means that the Web Server needs to rendezvous with a running application, rather than starting the application in order to explicitly communicate with it.<p>
-<a name="9110"></a>
-The FastCGI implementation basically creates a bidirectional connection between two processes that have no relationship. FastCGI uses a single connection for all the data associated with an application -- stdin, stdout, stderr, and environment variables. The data on the connection is encapsulated using a FastCGI protocol that allows stdin and the environment variables to share the same half connection (on the way in) and stdout and stderr to share the half connection (on the way out).<p>
-<a name="9020"></a>
-On the input side, the FastCGI application receives data on the connection, unpacks it to separate stdin from the environment variables and then invokes the application. On the output side, FastCGI wraps stdout and stderr with appropriate protocol headers, and sends the encapsulated data out to the server.<p>
-<a name="9032"></a>
-Since a FastCGI application does not always run on the same node as the HTTP server, we support two implementations of the connection: a <em>stream pipe</em><a href="#9645"><sup>1</sup></a>, for communications on the same machine, and TCP streams, for communication when the client and the server are on different machines.<p>
-<a name="8576"></a>
-<img src="ch1inta1.gif"><p>
-<a name="7549">
-<h5>Figure 2:  Flow of Data in FastCGI when server and application are on different machines</h5>
-</a><a name="7874">
-<h2> The fcgi_stdio Library: I/O Compatibility</h2>
-</a><a name="8977"></a>
-The implementation for I/O compatibility is that the library <code>fcgi_stdio.h</code> contains macros to translate the types and procedures defined in stdio.h into the appropriate FastCGI calls. For example, consider a FastCGI program written in C containing the following line of code:<p>
-<pre><a name="5877">
-fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");
-</a>
-</pre><a name="9659"></a>
-<code>fcgi_stdio.h</code> header file contains the macro<p>
-<pre><a name="6403">
-#define fprintf FCGI_fprintf
-</a>
-</pre><a name="6402"></a>
-So the preprocessor translates the <code>fprintf</code> call into the following call:<p>
-<pre><a name="6411">
-FCGI_fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");
-</a>
-</pre><a name="5888"></a>
-<code>FCGI_fprintf</code> takes the same arguments as <code>fprintf</code>. <p>
-<a name="9664"></a>
-The implementation of FCGI_fprintf tests the file to see if it is a normal C stream or a FastCGI stream, and calls the appropriate implementation.<p>
-<a name="6463"></a>
-The <code>fcgi_stdio.h</code> header file contains macros to translate calls to all ISO stdio.h routines (and all conventional Posix additions, such as <code>fileno</code>, <code>fdopen</code>, <code>popen</code>, and <code>pclose</code>) into their FastCGI equivalents. <p>
-<a name="9678">
-<h2> The fcgi_stdio Library: Binary compatibility</h2>
-</a><a name="9579"></a>
-The fcgi_stdio library provides full binary compatibility between FastCGI applications and CGI applications: you can run the same C binary as either CGI or FastCGI. <p>
-<a name="9580"></a>
-The implementation is in FCGI_Accept: the FCGI_Accept function tests its environment to determine whether the application was invoked as a CGI program or an FastCGI program. If it was invoked as a CGI program, the request loop will satisfy a single client request and then exit, producing CGI behavior.<p>
-<a name="8957"></a>
-<p>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="ap_guide.htm">[Prev]</a> <a href="ch2c.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<sup>1</sup><a name="9645"></a>
-UNIX Network Programming, W. Richard Stevens, 1990 Prentice-Hall, Section 7.9<p>
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:13 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide - Chapter 1, The Fast Common Gateway Interface\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ li.c2 {list-style: none}\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <A NAME="9432"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ 1 The Fast Common<BR>\r
+ Gateway Interface\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="7982"></A>\r
+ <P>\r
+ The Fast Common Gateway Interface (FastCGI) is an enhancement to the existing CGI (Common Gateway Interface),\r
+ which is a standard for interfacing external applications with Web servers.\r
+ </P>\r
+ <P>\r
+ <A NAME="8373"></A> FastCGI is a proposed open standard and we expect both free and commercial Web servers to\r
+ support it. FastCGI is included in Open Market WebServer and Secure WebServer, versions 2.0 and greater.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Advantages of FastCGI\r
+ </H1>\r
+ <A NAME="8369"></A>\r
+ <P>\r
+ FastCGI extends and enhances the CGI model in several ways:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="7832"></A>\r
+ </LI>\r
+ <LI>\r
+ FastCGI enables applications to persist between client requests, eliminating application start up overhead\r
+ and allowing the application to maintain state between client calls. <A NAME="7995"></A>\r
+ </LI>\r
+ <LI>\r
+ FastCGI enables applications to reside on remote systems (rather than having to reside on the same system\r
+ as the Web server) <A NAME="7997"></A>\r
+ </LI>\r
+ <LI>\r
+ FastCGI enables additional flexibility in application functionality, with explicit support for applications\r
+ that do client authentication and filtering of input.\r
+ </LI>\r
+ </UL>\r
+ <H2>\r
+ Long-lived Applications\r
+ </H2>\r
+ <A NAME="8458"></A>\r
+ <P>\r
+ CGI applications are ephemeral and short-lived: each time a client requests a CGI application, the server asks\r
+ the operating system to spawn a new CGI process. After the CGI process satisfies the request, the server kills\r
+ it. The server spawns and subsequently kills a new process for each client request.\r
+ </P>\r
+ <P>\r
+ <A NAME="8459"></A> FastCGI applications are long-lived, and can persist between client calls. The server\r
+ spawns the FastCGI process once and it continues to run and satisfy client requests until it is explicitly\r
+ terminated. You can also ask the Web server to start multiple copies of a FastCGI application, if you expect\r
+ that concurrent processing will improve the application's performance.\r
+ </P>\r
+ <P>\r
+ <A NAME="5761"></A> Long-lived applications have two important advantages over short-lived applications:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="7138"></A>\r
+ </LI>\r
+ <LI>\r
+ A short-lived application pays start up overhead on every request; a long-lived application spreads the\r
+ overhead over many requests. For an application that has a heavy start up cost, such as opening a database,\r
+ doing initialization on every call can be very inefficient. Reinitializing for every client is also very\r
+ inefficient for Perl programs, where the interpreter reads through the entire program before executing any\r
+ of it. <A NAME="9204"></A>\r
+ </LI>\r
+ <LI>\r
+ A long-lived application can cache information in memory between requests, allowing it to respond more\r
+ quickly to later requests.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="8733"></A>\r
+ <P>\r
+ FastCGI is not the only way to get a long-lived application on the Web, however. For example, there are many\r
+ existing search engines that are implemented as long-lived applications.\r
+ </P>\r
+ <P>\r
+ <A NAME="8734"></A> In most cases, these applications rely on customized Web servers. In other words, since\r
+ most Web servers do not support long-lived applications, a programmer must code this support into a Web\r
+ server. This approach requires a tremendous amount of work and also ties the application to a particular\r
+ server.\r
+ </P>\r
+ <P>\r
+ <A NAME="8735"></A> Another way to get a long-lived application is to write code that calls routines from the\r
+ Web server's API. This alternative involves a lot of extra coding, ties the application to a particular\r
+ Web server, and introduces problems of maintainability, scalability, and security.\r
+ </P>\r
+ <P>\r
+ <A NAME="8736"></A> We believe that FastCGI is the most general and flexible strategy for building long-lived\r
+ Web applications.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Separating Application and Server\r
+ </H2>\r
+ <A NAME="8446"></A>\r
+ <P>\r
+ CGI applications must run on the same node as the Web server; FastCGI applications can run on any node that\r
+ can be reached from your Web server using TCP/IP protocols. For example, you might want to run the FastCGI\r
+ application on a high-speed computer server or database engine, and run the Web server on a different node.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ FastCGI "Roles"\r
+ </H2>\r
+ <A NAME="8777"></A>\r
+ <P>\r
+ CGI and FastCGI applications are effective ways to allow an application to act as an extension to the Web\r
+ server. CGI provides no explicit support for different kinds of applications: under CGI, every application\r
+ receives an HTTP request, does something with it, and generates an HTTP response. FastCGI provides explicit\r
+ support for several common "roles" that applications can play.\r
+ </P>\r
+ <P>\r
+ <A NAME="8769"></A> The three roles supported by the WebServer 2.0 are:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="8409"></A>\r
+ </LI>\r
+ <LI>\r
+ Responder <A NAME="8410"></A>\r
+ </LI>\r
+ <LI>\r
+ Filter <A NAME="8411"></A>\r
+ </LI>\r
+ <LI>\r
+ Authorizer\r
+ </LI>\r
+ </UL>\r
+ <H3>\r
+ Responder Applications\r
+ </H3>\r
+ <A NAME="8679"></A>\r
+ <P>\r
+ A <EM>responder</EM> application is the most basic kind of FastCGI application: it receives the information\r
+ associated with an HTTP request and generates an HTTP response. Responder is the role most similar to\r
+ traditional CGI programming, and most FastCGI applications are responders.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H3>\r
+ Filter Applications\r
+ </H3>\r
+ <A NAME="8681"></A>\r
+ <P>\r
+ A <EM>filter</EM> FastCGI application receives the information associated with an HTTP request, plus an extra\r
+ stream of data from a file stored on the Web server, and generates a "filtered" version of the data\r
+ stream as an HTTP response.\r
+ </P>\r
+ <P>\r
+ <A NAME="8421"></A> With filter applications, the system administrator maps a particular MIME-type to a\r
+ particular filter FastCGI application. When a client requests a URL with that MIME-type, the Web server\r
+ invokes the filter application, which processes the file at the specified URL and sends a response (usually\r
+ HTML text) back to the client.\r
+ </P>\r
+ <P>\r
+ <A NAME="8422"></A> For example, suppose you write a filter FastCGI application that converts SGML text to\r
+ HTML, and map the extension .sgml (MIME-type SGML) to your filter FastCGI application. Now, suppose that a\r
+ user requests the following URL:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="8423">/www.aerjug.com/docs/chap1.sgml\r
+</A>\r
+</PRE>\r
+ <A NAME="8424"></A>\r
+ <P>\r
+ Given this URL, the Web server passes <CODE>chap1.sgml</CODE> as input to your filter FastCGI application,\r
+ which processes <CODE>chap1.sgml</CODE> and returns an HTML version of it to the requesting client.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H3>\r
+ Authorizer Applications\r
+ </H3>\r
+ <A NAME="8426"></A>\r
+ <P>\r
+ An <EM>authorizer</EM> FastCGI application receives the information in an HTTP request header and generates a\r
+ decision whether to authorize the request.\r
+ </P>\r
+ <P>\r
+ <A NAME="8428"></A> To mark a FastCGI application as having the authorizer role, the system administrator\r
+ names the application inside the server configuration file, using a directive called\r
+ <CODE>AuthorizeRegion</CODE>. (See the Open Market Web Server manual for information on server configuration\r
+ directives.)\r
+ </P>\r
+ <P>\r
+ <A NAME="8429"></A> When a client requests a URL that meets the <CODE>AuthorizeRegion</CODE> criteria, the Web\r
+ server calls your authorizer FastCGI application. If your application grants authorization (by returning a\r
+ response code of 200), the Web server resumes execution of commands in the <CODE>AuthorizeRegion</CODE>\r
+ section. If your application denies authorization (by returning any other response code), the Web server stops\r
+ processing subsequent commands in the <CODE>AuthorizeRegion</CODE> section, and returns the response from your\r
+ FastCGI application to the client.\r
+ </P>\r
+ <P>\r
+ <A NAME="8431"></A> Authorizer applications can return headers containing environment variables. Other CGI or\r
+ FastCGI programs accessing this request (including other authorizers) can access these environment variables.\r
+ The headers must have the following format:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="8432">Variable-<EM>name</EM>: <EM>value</EM>\r
+</A>\r
+</PRE>\r
+ <A NAME="8433"></A>\r
+ <P>\r
+ For example, the following header\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="8434">Variable-AUTH_METHOD: database lookup\r
+</A>\r
+</PRE>\r
+ <A NAME="8435"></A>\r
+ <P>\r
+ causes the environment variable <CODE>AUTH_METHOD</CODE> to be set to <CODE>"database lookup"</CODE>\r
+ for this request. Other CGI or FastCGI applications running on this request can access the value of\r
+ <CODE>AUTH_METHOD</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="8437"></A> Authorizer applications cannot successfully read from standard input. Any attempts to read\r
+ from standard input result in an immediate EOF.\r
+ </P>\r
+ <P>\r
+ <A NAME="8438"></A> All data that authorizer applications write to standard error will get written to the\r
+ traditional server error logs.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Writing FastCGI Applications\r
+ </H1>\r
+ <A NAME="9301"></A>\r
+ <P>\r
+ The work involved in writing a FastCGI application depends in large part on the I/O libraries that you use.\r
+ This manual describes how to write FastCGI applications in terms of the Open Market libraries, which are\r
+ available for C, Perl, and Tcl. FastCGI is an open standard and you are welcome to build your own libraries\r
+ for other languages as well, but this manual focuses on building FastCGI applications in the context of the\r
+ Open Market libraries.\r
+ </P>\r
+ <P>\r
+ <A NAME="9443"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="9450"></A> In general, the goal of the libraries is to make the job of writing a FastCGI application\r
+ as much like writing a CGI application as possible. For example, you use the same techniques for query string\r
+ decoding, HTML output to stdout, use of environment variables, and so on. When you use our libraries, porting\r
+ CGI applications to FastCGI is mostly a matter of restructuring the code to take advantage of FastCGI features\r
+ and libraries.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Code Structure\r
+ </H2>\r
+ <A NAME="9470"></A>\r
+ <P>\r
+ The main task of converting a CGI program into a FastCGI program is separating the initialization code from\r
+ the code that needs to run for each request. The structure should look something like this:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="9471">Initialization code\r
+</A>\r
+<A NAME="9472">Start of response loop\r
+</A>\r
+ <A NAME="9473"> body of response loop\r
+</A>\r
+<A NAME="9474">End of response loop\r
+</A>\r
+</PRE>\r
+ <A NAME="9475"></A>\r
+ <P>\r
+ The <EM>initialization code</EM> is run exactly once, when the application is initialized. Initialization code\r
+ usually performs time-consuming operations such as opening databases or calculating values for tables or\r
+ bitmaps.\r
+ </P>\r
+ <P>\r
+ <A NAME="9477"></A> The <EM>response loop</EM> runs continuously, waiting for client requests to arrive. The\r
+ loop starts with a call to <CODE>FCGI_Accept</CODE>, a routine in the FastCGI library. The\r
+ <CODE>FCGI_Accept</CODE> routine blocks program execution until a client requests the FastCGI application.\r
+ When a client request comes in, <CODE>FCGI_Accept</CODE> unblocks, runs one iteration of the response loop\r
+ body, and then blocks again waiting for another client request. The loop terminates only when the system\r
+ administrator or the Web server kills the FastCGI application.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Initial Environment Variables\r
+ </H2>\r
+ <A NAME="9786"></A>\r
+ <P>\r
+ When a FastCGI process starts up, it has not yet accepted a request, and therefore none of the CGI environment\r
+ variables are set.\r
+ </P>\r
+ <P>\r
+ <A NAME="9787"></A> You set the initial environment of a FastCGI process started by the <CODE>AppClass</CODE>\r
+ directive using the <CODE>-initial-env</CODE> option. The process would use this environment to configure its\r
+ options and locate files or databases.\r
+ </P>\r
+ <P>\r
+ <A NAME="9829"></A> In FastCGI processes started by the <CODE>AppClass</CODE> directive with the -affinity\r
+ option, the <CODE>FCGI_PROCESS_ID</CODE> variable is set in the initial environment (not in the environment of\r
+ a request). <CODE>FCGI_PROCESS_ID</CODE> is a decimal number in the range 0 to N - 1 where N is the number of\r
+ processes (argument to the <CODE>-processes</CODE> option to <CODE>AppClass</CODE>). The process would use\r
+ <CODE>FCGI_PROCESS_ID</CODE> in conjunction with other variables to locate session-related files or databases\r
+ during restart.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Per-Request Environment Variables\r
+ </H2>\r
+ <A NAME="9481"></A>\r
+ <P>\r
+ In general, FastCGI uses the same per-request environment variables as CGI, and you access the values of\r
+ environment variables in FastCGI applications just as you would in CGI applications. The only differences are\r
+ as follows:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="9483"></A>\r
+ </LI>\r
+ <LI>\r
+ In Authorizer FastCGI applications, the Web server unsets the <CODE>PATH_INFO</CODE>,\r
+ <CODE>PATH_TRANSLATED</CODE>, and <CODE>CONTENT_LENGTH</CODE> variables. <A NAME="9484"></A>\r
+ </LI>\r
+ <LI>\r
+ In Filter FastCGI applications, the Web server sets two additional environment variables: \r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="9486"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>FILE_LAST_MOD</CODE>: The Web server sets <CODE>FILE_LAST_MOD</CODE> to the date and time that\r
+ filter input file was last modified. The format is the number of seconds since midnight (UTC),\r
+ January 1, 1970. <A NAME="9488"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>FCGI_DATA_LENGTH</CODE>: The application reads at most <CODE>FCGI_DATA_LENGTH</CODE> bytes from\r
+ the data stream before receiving the end-of-stream indication.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="9490"></A>\r
+ </LI>\r
+ <LI>\r
+ FastCGI sets <CODE>FCGI_ROLE</CODE> for each request to <CODE>RESPONDER</CODE>, <CODE>AUTHORIZER</CODE>, or\r
+ <CODE>FILTER</CODE>.\r
+ </LI>\r
+ </UL>\r
+ <H2>\r
+ Building FastCGI Applications in C\r
+ </H2>\r
+ <A NAME="9049"></A>\r
+ <P>\r
+ The Software Development Toolkit that accompanies WebServer 2.0 contains two libraries, fcgi_stdio and\r
+ fcgiapp, for building FastCGI applications in C.\r
+ </P>\r
+ <P>\r
+ <A NAME="9723"></A> The fcgi_stdio library implements our philosophy of making FastCGI applications similar to\r
+ CGI applications, and provides full binary compatibility between FastCGI applications and CGI applications:\r
+ you can run the same C binary as either CGI or FastCGI.\r
+ </P>\r
+ <P>\r
+ <A NAME="9545"></A> The fcgiapp library is more specific to FastCGI, and doesn't attempt the veneer of\r
+ CGI.\r
+ </P>\r
+ <P>\r
+ <A NAME="9731"></A> We recommend that you use the fcgi_stdio library, and this manual describes the routines\r
+ in that library. The documentation for the fcgiapp library is in the code in the development kit.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Building FastCGI Applications in Perl\r
+ </H2>\r
+ <A NAME="9581"></A>\r
+ <P>\r
+ To build FastCGI applications in Perl, you need a FastCGI-savvy version of Perl, plus the FastCGI extension to\r
+ Perl. We build FastCGI-savvy versions of the Perl interpreter for several common platforms and make them\r
+ available on our Website. For details and examples, see Chapter <A HREF="ch3perl.htm#3659">3, "Developing\r
+ FastCGI Applications in Perl," on page 17</A>.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ Building FastCGI Applications in Tcl\r
+ </H2>\r
+ <A NAME="9586"></A>\r
+ <P>\r
+ To build FastCGI applications in Tcl, you need a FastCGI-savvy version of Tcl. We build FastCGI-savvy versions\r
+ of the Tcl interpreter for several common platforms and make them available on our Website. For details and\r
+ examples, see Chapter <A HREF="ch4tcl.htm#3659">4, "Developing FastCGI Applications in Tcl," on page\r
+ 19</A>.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Implementation Details\r
+ </H1>\r
+ <A NAME="8066"></A>\r
+ <P>\r
+ The FastCGI application libraries are designed to shield you from the details of the FastCGI design. This\r
+ section is designed for the curious reader who would like some low-level understanding. If you are not curious\r
+ about the implementation, you can happily skip this section.\r
+ </P>\r
+ <P>\r
+ <A NAME="8554"></A> As shown in the following figure, CGI applications use the three standard POSIX streams\r
+ (<CODE>stdin</CODE>, <CODE>stdout</CODE>, and <CODE>stderr</CODE>), plus environment variables, to communicate\r
+ with an HTTP server.\r
+ </P>\r
+ <P>\r
+ <A NAME="8359"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1intra.gif">\r
+ </P>\r
+ <P>\r
+ <A NAME="4295"></A>\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H5>\r
+ Figure 1: Flow of Data in CGI\r
+ </H5>\r
+ <A NAME="9001"></A>\r
+ <P>\r
+ The fundamental difference between FastCGI and CGI is that FastCGI applications are long-lived, which means\r
+ that the Web Server needs to rendezvous with a running application, rather than starting the application in\r
+ order to explicitly communicate with it.\r
+ </P>\r
+ <P>\r
+ <A NAME="9110"></A> The FastCGI implementation basically creates a bidirectional connection between two\r
+ processes that have no relationship. FastCGI uses a single connection for all the data associated with an\r
+ application -- stdin, stdout, stderr, and environment variables. The data on the connection is encapsulated\r
+ using a FastCGI protocol that allows stdin and the environment variables to share the same half connection (on\r
+ the way in) and stdout and stderr to share the half connection (on the way out).\r
+ </P>\r
+ <P>\r
+ <A NAME="9020"></A> On the input side, the FastCGI application receives data on the connection, unpacks it to\r
+ separate stdin from the environment variables and then invokes the application. On the output side, FastCGI\r
+ wraps stdout and stderr with appropriate protocol headers, and sends the encapsulated data out to the server.\r
+ </P>\r
+ <P>\r
+ <A NAME="9032"></A> Since a FastCGI application does not always run on the same node as the HTTP server, we\r
+ support two implementations of the connection: a <EM>stream pipe</EM><A HREF="#9645"><SUP>1</SUP></A>, for\r
+ communications on the same machine, and TCP streams, for communication when the client and the server are on\r
+ different machines.\r
+ </P>\r
+ <P>\r
+ <A NAME="8576"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1inta1.gif">\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H5>\r
+ Figure 2: Flow of Data in FastCGI when server and application are on different machines\r
+ </H5>\r
+ <H2>\r
+ The fcgi_stdio Library: I/O Compatibility\r
+ </H2>\r
+ <A NAME="8977"></A>\r
+ <P>\r
+ The implementation for I/O compatibility is that the library <CODE>fcgi_stdio.h</CODE> contains macros to\r
+ translate the types and procedures defined in stdio.h into the appropriate FastCGI calls. For example,\r
+ consider a FastCGI program written in C containing the following line of code:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="5877">fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");\r
+</A>\r
+</PRE>\r
+ <A NAME="9659"></A> <CODE>fcgi_stdio.h</CODE>\r
+ <P>\r
+ header file contains the macro\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="6403">#define fprintf FCGI_fprintf\r
+</A>\r
+</PRE>\r
+ <A NAME="6402"></A>\r
+ <P>\r
+ So the preprocessor translates the <CODE>fprintf</CODE> call into the following call:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="6411">FCGI_fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");\r
+</A>\r
+</PRE>\r
+ <A NAME="5888"></A> <CODE>FCGI_fprintf</CODE>\r
+ <P>\r
+ takes the same arguments as <CODE>fprintf</CODE>.\r
+ </P>\r
+ <P>\r
+ <A NAME="9664"></A> The implementation of FCGI_fprintf tests the file to see if it is a normal C stream or a\r
+ FastCGI stream, and calls the appropriate implementation.\r
+ </P>\r
+ <P>\r
+ <A NAME="6463"></A> The <CODE>fcgi_stdio.h</CODE> header file contains macros to translate calls to all ISO\r
+ stdio.h routines (and all conventional Posix additions, such as <CODE>fileno</CODE>, <CODE>fdopen</CODE>,\r
+ <CODE>popen</CODE>, and <CODE>pclose</CODE>) into their FastCGI equivalents.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H2>\r
+ The fcgi_stdio Library: Binary compatibility\r
+ </H2>\r
+ <A NAME="9579"></A>\r
+ <P>\r
+ The fcgi_stdio library provides full binary compatibility between FastCGI applications and CGI applications:\r
+ you can run the same C binary as either CGI or FastCGI.\r
+ </P>\r
+ <P>\r
+ <A NAME="9580"></A> The implementation is in FCGI_Accept: the FCGI_Accept function tests its environment to\r
+ determine whether the application was invoked as a CGI program or an FastCGI program. If it was invoked as a\r
+ CGI program, the request loop will satisfy a single client request and then exit, producing CGI behavior.\r
+ </P>\r
+ <P>\r
+ <A NAME="8957"></A>\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <SUP>1</SUP><A NAME="9645"></A>\r
+ <P>\r
+ UNIX Network Programming, W. Richard Stevens, 1990 Prentice-Hall, Section 7.9\r
+ </P>\r
+ <P>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:13 -->\r
+ </P>\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide - Chapter 2, Developing FastCGI Applications in C</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="ch1intro.htm">[Prev]</a> <a href="ch3perl.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="3659">
-<center><h1>2 Developing FastCGI <br>Applications in C</h1></center>
-</a><a name="917"></a>
-This chapter explains how to code FastCGI applications in C and how to build them into executables. <p>
-<a name="4230"></a>
-If you are converting a CGI application into a FastCGI application, in many cases you will only need to add a few lines of code. For more complex applications, you may also need to rearrange some code.<p>
-<a name="5371">
-<h1> The I/O Libraries</h1>
-</a><a name="5384"></a>
-The FastCGI Software Development Kit that accompanies Open Market WebServer 2.0 includes I/O libraries to simplify the job of converting existing CGI applications to FastCGI or writing new FastCGI applications. There are two libraries in the kit: fcgi_stdio and fcgiapp. You must include one of these header files in your program:<p>
-<ul><a name="5386"></a>
-<li><code>fcgi_stdio.h</code>
-<a name="4237"></a>
-<li><code>fcgiapp.h</code>
-</ul><a name="4199"></a>
-The <code>fcgi_stdio</code> library is a layer on top of the <code>fcgiapp</code> library, and we recommend strongly that you use it, both for converting existing CGI applications and for writing new FastCGI applications. The fcgi_stdio library offers several advantages:<p>
-<ul><a name="5811"></a>
-<li>Simplicity: there are only 3 new API calls to learn
-<a name="5828"></a>
-<li>Familiarity: If you are converting a CGI application to FastCGI, you will find few changes between CGI and FastCGI. We designed our library to make the job of building a FastCGI application as similar as possible to that of building a FastCGI application: you use the same environment variables, same techniques for parsing query strings, the same I/O routines, and so on.
-<a name="5817"></a>
-<li>Convenience: the library provides full binary compatibility between CGI and FastCGI. That is, you can run the same binary as either CGI or FastCGI.
-</ul><a name="5399"></a>
-The fcgiapp library is more specific to FastCGI, without trying to provide the veneer of familiarity with CGI. This manual describes the fcgi_stdio library; the fcgiapp library is documented in the header files that accompany the development kit. <p>
-<a name="5847">
-<h1> Code Structure</h1>
-</a><a name="4240"></a>
-To structure code for FastCGI, you separate your code into two sections:<p>
-<ul><a name="4200"></a>
-<li>Initialization section, which is executed only once.
-<a name="4201"></a>
-<li>Response loop section, which gets executed every time the FastCGI script gets called.
-</ul><a name="4202"></a>
-A response loop typically has the following format:<p>
-<pre><a name="4203">
-while (FCGI_Accept() >= 0) {
-</a>
-<a name="4204">
-# body of response loop
-</a>
-<a name="4205">
-}
-</a>
-</pre><a name="4206"></a>
-The <code>FCGI_Accept</code> blocks until a client request comes in, and then returns 0. If there is a system failure, or the system administrator terminates the process, Accept will return -1. <p>
-<a name="5852"></a>
-If the application was invoked as a CGI program, the first call to Accept returns 0 and the second always returns -1, producing CGI behavior. (See <a href="apaman.htm#95860">"FCGI_Accept (3)" on page  21</a> for details.)<p>
-<a name="5909"></a>
-Also note that the CGI world encourages small scripts, whereas FastCGI encourages combining scripts. You may choose to rethink the overall structure of your applications to take better advantage of FastCGI performance gains.<p>
-<a name="5373">
-<h1> Example 1: TinyFastCGI</h1>
-</a><a name="4263">
-Here is a simple example of a responder FastCGI application written in C:<p>
-<pre>
-#include "fcgi_stdio.h" /* fcgi library; put it first*/<br>#include <stdlib.h>
-
-int count;
-
-void initialize(void)
-{
- count=0;
-}
-
-void main(void)
-{
-/* Initialization. */
- initialize();
-
-/* Response loop. */
- while (FCGI_Accept() >= 0) {
- printf("Content-type: text/html\r\n"
- "\r\n"
- "<title>FastCGI Hello! (C, fcgi_stdio library)</title>"
- "<h1>FastCGI Hello! (C, fcgi_stdio library)</h1>"
- "Request number %d running on host <i>%s</i>\n",
- ++count, getenv("SERVER_HOSTNAME"));
- }
-}
-</pre>
-<h1> Example 2: Prime Number Generator</h1>
-</a><a name="4182"></a>
-Consider a responder application that generates the n-th prime number. <p>
-<a name="5217"></a>
-A CGI application would have no efficient way of solving this problem. For example, if the user asks for the 50,000th prime number, a CGI application would have to calculate the first prime number, then the second, and so on, up until the 50,000th. The application would then terminate, taking with it all its hard-earned calculations. If a client then asks for the 49,000th prime number, the server will have to spawn a new CGI application which will have to start calculating prime numbers from scratch.<p>
-<a name="4315"></a>
-FastCGI applications can be much more efficient at this sort of problem, since they can maintain state. A FastCGI application can calculate an extensive table of prime numbers in its initialization phase and then keep the table around indefinitely. Whenever a client requests a particular prime number, the response loop merely needs to look it up in the table. <p>
-<a name="4343"></a>
-Here is the code for the prime number example:<p>
-<pre>
-#include "fcgi_stdio.h"
-#include <stdlib.h>
-#include <string.h>
-
-#define POTENTIALLY_PRIME 0
-#define COMPOSITE 1
-#define VALS_IN_SIEVE_TABLE 1000000
-#define MAX_NUMBER_OF_PRIME_NUMBERS 78600
-
-/* All initialized to POTENTIALLY_PRIME */
-long int sieve_table[VALS_IN_SIEVE_TABLE];
-long int prime_table[MAX_NUMBER_OF_PRIME_NUMBERS];
-/* Use Sieve of Erastothenes method of building
- a prime number table. */
-void
-initialize_prime_table(void)
-{
- long int prime_counter=1;
- long int current_prime=2, c, d;
-
- prime_table[prime_counter]=current_prime;
-
- while (current_prime < VALS_IN_SIEVE_TABLE) {
- /* Mark off composite numbers. */
- for (c = current_prime; c <= VALS_IN_SIEVE_TABLE;
- c += current_prime) {
- sieve_table[c] = COMPOSITE;
- }
-
- /* Find the next prime number. */
- for (d=current_prime+1; sieve_table[d] == COMPOSITE; d++);
- /* Put the new prime number into the table. */
- prime_table[++prime_counter]=d;
- current_prime=d;
- }
-}
-
-
-void main(void)
-{
- char *query_string;
- long int n;
-
- initialize_prime_table();
-
- while(FCGI_Accept() >= 0) {
- /*
- * Produce the necessary HTTP header.
- */
- printf("Content-type: text/html\r\n"
- "\r\n");
- /*
- * Produce the constant part of the HTML document.
- */
- printf("<title>Prime FastCGI</title>\n"
- "<h1>Prime FastCGI</h1>\n");
- /*
- * Read the query string and produce the variable part
- * of the HTML document.
- */
- query_string = getenv("QUERY_STRING");
- if(query_string == NULL) {
- printf("Usage: Specify a positive number in the query string.\n");
- } else {
- query_string = strchr(query_string, `=') + 1;
- n = strtol(query_string);
- if(n < 1) {
- printf("The query string `%s' is not a positive number.\n",
- query_string);
- } else if(n > MAX_NUMBER_OF_PRIME_NUMBERS) {
- printf("The number %d is too large for this program.\n", n);
- } else
- printf("The %ldth prime number is %ld.\n", prime_table[n]);
- }
- }
- } /* while FCGI_Accept */
-}
-</pre><a name="5349"></a>
-This application has a noticeable start up cost while it initializes the table, but subsequent accesses are fast.<p>
-<a name="5151">
-<h1> Building</h1>
-</a><a name="4630"></a>
-This section explains how to build and debug FastCGI applications written in C.<p>
-<a name="4629"></a>
-The C preprocessor needs to know the location of the <code>fcgi_stdio.h</code> header file, which is at the following pathname:<p>
-<pre><a name="4642">
-<em>$toolkit</em>/include/fcgi_stdio.h
-</a>
-</pre><a name="4645"></a>
-where <em>$toolkit</em> symbolizes the directory in which you have installed the Software Development Kit for FastCGI. <p>
-<a name="4760"></a>
-The linker needs to know the location of the <code>libfcgi.a</code> library file, which is at the following pathname:<p>
-<pre><a name="4647">
-<em>$toolkit</em>/libfcgi/libfcgi.a
-</a>
-</pre><a name="4648"></a>
-If your linker does not search the Berkeley socket library, then you must add linker directives to force this search.<p>
-<a name="4773"></a>
-We provide a sample application <code>Makefile</code> at the following pathname: <p>
-<pre><a name="4649">
-<em>$toolkit</em>/examples/Makefile
-</a>
-</pre><a name="4652"></a>
-This <code>Makefile</code> contains the necessary rules and pathnames to build the C FastCGI applications accompanying the toolkit. To build all the applications, type:<p>
-<pre><a name="4653">
-$ ./configure<br>$ make
-</a>
-</pre><a name="4190">
-<h1> Memory Leaks</h1>
-</a><a name="4178"></a>
-Memory leaks are seldom a problem in CGI programming because CGI applications rarely run long enough to be concerned with leaks. However, memory leaks can become a problem in FastCGI applications, particularly if each call to a popular FastCGI application causes additional memory to leak. <p>
-<a name="4785"></a>
-When converting to FastCGI, you can either use a tool such as Purify from Pure Software to discover and fix storage leaks or you can run a C garbage collector such as Great Circle from Geodesic Systems. <p>
-<a name="4972"></a>
-<p>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="ch1intro.htm">[Prev]</a> <a href="ch3perl.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:16 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide - Chapter 2, Developing FastCGI Applications in C\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ li.c2 {list-style: none}\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch1intro.htm">[Prev]</A> <A HREF="ch3perl.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <A NAME="3659"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ 2 Developing FastCGI<BR>\r
+ Applications in C\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="917"></A>\r
+ <P>\r
+ This chapter explains how to code FastCGI applications in C and how to build them into executables.\r
+ </P>\r
+ <P>\r
+ <A NAME="4230"></A> If you are converting a CGI application into a FastCGI application, in many cases you will\r
+ only need to add a few lines of code. For more complex applications, you may also need to rearrange some code.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ The I/O Libraries\r
+ </H1>\r
+ <A NAME="5384"></A>\r
+ <P>\r
+ The FastCGI Software Development Kit that accompanies Open Market WebServer 2.0 includes I/O libraries to\r
+ simplify the job of converting existing CGI applications to FastCGI or writing new FastCGI applications. There\r
+ are two libraries in the kit: fcgi_stdio and fcgiapp. You must include one of these header files in your\r
+ program:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="5386"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>fcgi_stdio.h</CODE> <A NAME="4237"></A>\r
+ </LI>\r
+ <LI>\r
+ <CODE>fcgiapp.h</CODE>\r
+ </LI>\r
+ </UL>\r
+ <A NAME="4199"></A>\r
+ <P>\r
+ The <CODE>fcgi_stdio</CODE> library is a layer on top of the <CODE>fcgiapp</CODE> library, and we recommend\r
+ strongly that you use it, both for converting existing CGI applications and for writing new FastCGI\r
+ applications. The fcgi_stdio library offers several advantages:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="5811"></A>\r
+ </LI>\r
+ <LI>\r
+ Simplicity: there are only 3 new API calls to learn <A NAME="5828"></A>\r
+ </LI>\r
+ <LI>\r
+ Familiarity: If you are converting a CGI application to FastCGI, you will find few changes between CGI and\r
+ FastCGI. We designed our library to make the job of building a FastCGI application as similar as possible\r
+ to that of building a FastCGI application: you use the same environment variables, same techniques for\r
+ parsing query strings, the same I/O routines, and so on. <A NAME="5817"></A>\r
+ </LI>\r
+ <LI>\r
+ Convenience: the library provides full binary compatibility between CGI and FastCGI. That is, you can run\r
+ the same binary as either CGI or FastCGI.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="5399"></A>\r
+ <P>\r
+ The fcgiapp library is more specific to FastCGI, without trying to provide the veneer of familiarity with CGI.\r
+ This manual describes the fcgi_stdio library; the fcgiapp library is documented in the header files that\r
+ accompany the development kit.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Code Structure\r
+ </H1>\r
+ <A NAME="4240"></A>\r
+ <P>\r
+ To structure code for FastCGI, you separate your code into two sections:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="4200"></A>\r
+ </LI>\r
+ <LI>\r
+ Initialization section, which is executed only once. <A NAME="4201"></A>\r
+ </LI>\r
+ <LI>\r
+ Response loop section, which gets executed every time the FastCGI script gets called.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="4202"></A>\r
+ <P>\r
+ A response loop typically has the following format:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4203">while (FCGI_Accept() >= 0) {\r
+</A>\r
+<A NAME="4204"># body of response loop\r
+</A>\r
+<A NAME="4205">}\r
+</A>\r
+</PRE>\r
+ <A NAME="4206"></A>\r
+ <P>\r
+ The <CODE>FCGI_Accept</CODE> blocks until a client request comes in, and then returns 0. If there is a system\r
+ failure, or the system administrator terminates the process, Accept will return -1.\r
+ </P>\r
+ <P>\r
+ <A NAME="5852"></A> If the application was invoked as a CGI program, the first call to Accept returns 0 and\r
+ the second always returns -1, producing CGI behavior. (See <A HREF="apaman.htm#95683">"FCGI_Accept\r
+ (3)" on page 21</A> for details.)\r
+ </P>\r
+ <P>\r
+ <A NAME="5909"></A> Also note that the CGI world encourages small scripts, whereas FastCGI encourages\r
+ combining scripts. You may choose to rethink the overall structure of your applications to take better\r
+ advantage of FastCGI performance gains.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Example 1: TinyFastCGI\r
+ </H1>\r
+ <A NAME="4263">Here is a simple example of a responder FastCGI application written in C:</A><BR>\r
+ <BR>\r
+<PRE>\r
+#include "fcgi_stdio.h" /* fcgi library; put it first*/<BR>\r
+#include <stdlib.h>\r
+\r
+int count;\r
+\r
+void initialize(void)\r
+{\r
+ count=0;\r
+}\r
+\r
+void main(void)\r
+{\r
+/* Initialization. */ \r
+ initialize();\r
+\r
+/* Response loop. */\r
+ while (FCGI_Accept() >= 0) {\r
+ printf("Content-type: text/html\r\n"\r
+ "\r\n"\r
+ "<title>FastCGI Hello! (C, fcgi_stdio library)</title>"\r
+ "<h1>FastCGI Hello! (C, fcgi_stdio library)</h1>"\r
+ "Request number %d running on host <i>%s</i>\n",\r
+ ++count, getenv("SERVER_HOSTNAME"));\r
+ }\r
+}\r
+</PRE>\r
+ <H1>\r
+ Example 2: Prime Number Generator\r
+ </H1>\r
+ <A NAME="4182"></A>\r
+ <P>\r
+ Consider a responder application that generates the n-th prime number.\r
+ </P>\r
+ <P>\r
+ <A NAME="5217"></A> A CGI application would have no efficient way of solving this problem. For example, if the\r
+ user asks for the 50,000th prime number, a CGI application would have to calculate the first prime number,\r
+ then the second, and so on, up until the 50,000th. The application would then terminate, taking with it all\r
+ its hard-earned calculations. If a client then asks for the 49,000th prime number, the server will have to\r
+ spawn a new CGI application which will have to start calculating prime numbers from scratch.\r
+ </P>\r
+ <P>\r
+ <A NAME="4315"></A> FastCGI applications can be much more efficient at this sort of problem, since they can\r
+ maintain state. A FastCGI application can calculate an extensive table of prime numbers in its initialization\r
+ phase and then keep the table around indefinitely. Whenever a client requests a particular prime number, the\r
+ response loop merely needs to look it up in the table.\r
+ </P>\r
+ <P>\r
+ <A NAME="4343"></A> Here is the code for the prime number example:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+#include "fcgi_stdio.h"\r
+#include <stdlib.h>\r
+#include <string.h>\r
+\r
+#define POTENTIALLY_PRIME 0\r
+#define COMPOSITE 1\r
+#define VALS_IN_SIEVE_TABLE 1000000\r
+#define MAX_NUMBER_OF_PRIME_NUMBERS 78600 \r
+\r
+/* All initialized to POTENTIALLY_PRIME */\r
+long int sieve_table[VALS_IN_SIEVE_TABLE]; \r
+long int prime_table[MAX_NUMBER_OF_PRIME_NUMBERS]; \r
+/* Use Sieve of Erastothenes method of building \r
+ a prime number table. */\r
+void\r
+initialize_prime_table(void)\r
+{\r
+ long int prime_counter=1;\r
+ long int current_prime=2, c, d; \r
+ \r
+ prime_table[prime_counter]=current_prime;\r
+\r
+ while (current_prime < VALS_IN_SIEVE_TABLE) {\r
+ /* Mark off composite numbers. */\r
+ for (c = current_prime; c <= VALS_IN_SIEVE_TABLE; \r
+ c += current_prime) {\r
+ sieve_table[c] = COMPOSITE; \r
+ }\r
+\r
+ /* Find the next prime number. */\r
+ for (d=current_prime+1; sieve_table[d] == COMPOSITE; d++); \r
+ /* Put the new prime number into the table. */ \r
+ prime_table[++prime_counter]=d; \r
+ current_prime=d;\r
+ }\r
+}\r
+\r
+\r
+void main(void)\r
+{\r
+ char *query_string;\r
+ long int n;\r
+\r
+ initialize_prime_table();\r
+\r
+ while(FCGI_Accept() >= 0) {\r
+ /*\r
+ * Produce the necessary HTTP header.\r
+ */\r
+ printf("Content-type: text/html\r\n"\r
+ "\r\n");\r
+ /*\r
+ * Produce the constant part of the HTML document.\r
+ */\r
+ printf("<title>Prime FastCGI</title>\n"\r
+ "<h1>Prime FastCGI</h1>\n");\r
+ /*\r
+ * Read the query string and produce the variable part\r
+ * of the HTML document.\r
+ */\r
+ query_string = getenv("QUERY_STRING");\r
+ if(query_string == NULL) {\r
+ printf("Usage: Specify a positive number in the query string.\n");\r
+ } else {\r
+ query_string = strchr(query_string, `=') + 1;\r
+ n = strtol(query_string);\r
+ if(n < 1) {\r
+ printf("The query string `%s' is not a positive number.\n",\r
+ query_string);\r
+ } else if(n > MAX_NUMBER_OF_PRIME_NUMBERS) {\r
+ printf("The number %d is too large for this program.\n", n);\r
+ } else\r
+ printf("The %ldth prime number is %ld.\n", prime_table[n]);\r
+ }\r
+ }\r
+ } /* while FCGI_Accept */\r
+}\r
+</PRE>\r
+ <A NAME="5349"></A>\r
+ <P>\r
+ This application has a noticeable start up cost while it initializes the table, but subsequent accesses are\r
+ fast.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Building\r
+ </H1>\r
+ <A NAME="4630"></A>\r
+ <P>\r
+ This section explains how to build and debug FastCGI applications written in C.\r
+ </P>\r
+ <P>\r
+ <A NAME="4629"></A> The C preprocessor needs to know the location of the <CODE>fcgi_stdio.h</CODE> header\r
+ file, which is at the following pathname:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4642"><EM>$toolkit</EM>/include/fcgi_stdio.h\r
+</A>\r
+</PRE>\r
+ <A NAME="4645"></A>\r
+ <P>\r
+ where <EM>$toolkit</EM> symbolizes the directory in which you have installed the Software Development Kit for\r
+ FastCGI.\r
+ </P>\r
+ <P>\r
+ <A NAME="4760"></A> The linker needs to know the location of the <CODE>libfcgi.a</CODE> library file, which is\r
+ at the following pathname:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4647"><EM>$toolkit</EM>/libfcgi/libfcgi.a \r
+</A>\r
+</PRE>\r
+ <A NAME="4648"></A>\r
+ <P>\r
+ If your linker does not search the Berkeley socket library, then you must add linker directives to force this\r
+ search.\r
+ </P>\r
+ <P>\r
+ <A NAME="4773"></A> We provide a sample application <CODE>Makefile</CODE> at the following pathname:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4649"><EM>$toolkit</EM>/examples/Makefile\r
+</A>\r
+</PRE>\r
+ <A NAME="4652"></A>\r
+ <P>\r
+ This <CODE>Makefile</CODE> contains the necessary rules and pathnames to build the C FastCGI applications\r
+ accompanying the toolkit. To build all the applications, type:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4653">$ ./configure<BR>\r
+$ make \r
+</A>\r
+</PRE>\r
+ <H1>\r
+ Memory Leaks\r
+ </H1>\r
+ <A NAME="4178"></A>\r
+ <P>\r
+ Memory leaks are seldom a problem in CGI programming because CGI applications rarely run long enough to be\r
+ concerned with leaks. However, memory leaks can become a problem in FastCGI applications, particularly if each\r
+ call to a popular FastCGI application causes additional memory to leak.\r
+ </P>\r
+ <P>\r
+ <A NAME="4785"></A> When converting to FastCGI, you can either use a tool such as Purify from Pure Software to\r
+ discover and fix storage leaks or you can run a C garbage collector such as Great Circle from Geodesic\r
+ Systems.\r
+ </P>\r
+ <P>\r
+ <A NAME="4972"></A>\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch1intro.htm">[Prev]</A> <A HREF="ch3perl.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:16 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide - Chapter 3, Developing FastCGI Applications in Perl</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="ch2c.htm">[Prev]</a> <a href="ch4tcl.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="3659">
-<center><h1>3 Developing FastCGI <br>Applications in Perl</h1></center>
-</a><a name="917"></a>
-This chapter explains how to code FastCGI applications in Perl. Before you can build FastCGI applications in Perl, you must have a FastCGI-savvy version of the Perl interpreter. Open Market develops such Perl binaries for popular platforms and makes them available with our developer's kit. <p>
-<a name="5008"></a>
-The FastCGI-savvy binaries are extensions of standard Perl, and are intended to replace your existing Perl installation. There is no need to maintain two versions of Perl: the version that we supply will work fine when invoked from a shell or a CGI program. There are also directions in the developer's kit for how to make your own FastCGI-savvy Perl, if you need a version for some platform that we don't supply.<p>
-<a name="4369"></a>
-FastCGI is ideal for applications written in Perl, because it provides a huge performance gain. When you run a Perl script, the Perl interpreter analyzes the entire script before executing any of it. With FastCGI, you can factor out this initialization cost and pay it only once, making execution of the actual script much faster in response to client calls.<p>
-<a name="4183">
-<h1> Getting Started</h1>
-</a><a name="4234"></a>
-The first line of any Perl script typically specifies the pathname of the Perl interpreter itself. You must specify the pathname of a FastCGI-savvy Perl. <p>
-<a name="4235"></a>
-Next, you must tell Perl to load the FastCGI extension. To do so, place the following line near the beginning of every FastCGI script: <p>
-<pre><a name="4210">
-use FCGI;
-</a>
-</pre><a name="4212"></a>
-Then, you have to divide FastCGI scripts into the following two sections:<p>
-<ul><a name="4242"></a>
-<li>Initialization section, which is executed only once.
-<a name="4243"></a>
-<li>Response loop section, which gets executed every time the FastCGI script gets called.
-</ul><a name="4248"></a>
-A response loop typically has the following format:<p>
-<pre><a name="4255">
-while (FCGI::accept >= 0) {
-</a>
-<a name="4256">
-# body of response loop
-</a>
-<a name="4257">
-}
-</a>
-</pre><a name="4258"></a>
-The <code>accept</code> call returns 0 whenever a client requests the FastCGI script. Otherwise, the <code>accept</code> call returns -1. <p>
-<a name="5002">
-<h1> Example: TinyFastCGI</h1>
-</a><a name="4588"></a>
-Here is a simple example of a FastCGI application written in Perl:<p>
-<pre><a name="4589"></a>
-#!fcgi-savvy-perl
-
-use FCGI; # Imports the library; required line
-
-# Initialization code
-
-$cnt = 0;
-
-# Response loop
-
-while (FCGI::accept >= 0) {
- print "Content-type: text/html\r\n\r\n";
- print "<head>\n<title>FastCGI Demo Page (perl)</title>\n</head>\n";
- print "<h1>FastCGI Demo Page (perl)</h1>\n";
- print "This is coming from a FastCGI server.\n<BR>\n";
- print "Running on <EM>$ENV{SERVER_NAME}</EM> to <EM>$ENV{REMOTE_HOST}</EM>\n<BR>\n";
- $cnt++;
- print "This is connection number $cnt\n";
-}
-</pre>
-<p>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="ch2c.htm">[Prev]</a> <a href="ch4tcl.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:18 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide - Chapter 3, Developing FastCGI Applications in Perl\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ li.c2 {list-style: none}\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch2c.htm">[Prev]</A> <A HREF="ch4tcl.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <A NAME="3659"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ 3 Developing FastCGI<BR>\r
+ Applications in Perl\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="917"></A>\r
+ <P>\r
+ This chapter explains how to code FastCGI applications in Perl. Before you can build FastCGI applications in\r
+ Perl, you must have a FastCGI-savvy version of the Perl interpreter. Open Market develops such Perl binaries\r
+ for popular platforms and makes them available with our developer's kit.\r
+ </P>\r
+ <P>\r
+ <A NAME="5008"></A> The FastCGI-savvy binaries are extensions of standard Perl, and are intended to replace\r
+ your existing Perl installation. There is no need to maintain two versions of Perl: the version that we supply\r
+ will work fine when invoked from a shell or a CGI program. There are also directions in the developer's\r
+ kit for how to make your own FastCGI-savvy Perl, if you need a version for some platform that we don't\r
+ supply.\r
+ </P>\r
+ <P>\r
+ <A NAME="4369"></A> FastCGI is ideal for applications written in Perl, because it provides a huge performance\r
+ gain. When you run a Perl script, the Perl interpreter analyzes the entire script before executing any of it.\r
+ With FastCGI, you can factor out this initialization cost and pay it only once, making execution of the actual\r
+ script much faster in response to client calls.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Getting Started\r
+ </H1>\r
+ <A NAME="4234"></A>\r
+ <P>\r
+ The first line of any Perl script typically specifies the pathname of the Perl interpreter itself. You must\r
+ specify the pathname of a FastCGI-savvy Perl.\r
+ </P>\r
+ <P>\r
+ <A NAME="4235"></A> Next, you must tell Perl to load the FastCGI extension. To do so, place the following line\r
+ near the beginning of every FastCGI script:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4210">use FCGI;\r
+</A>\r
+</PRE>\r
+ <A NAME="4212"></A>\r
+ <P>\r
+ Then, you have to divide FastCGI scripts into the following two sections:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="4242"></A>\r
+ </LI>\r
+ <LI>\r
+ Initialization section, which is executed only once. <A NAME="4243"></A>\r
+ </LI>\r
+ <LI>\r
+ Response loop section, which gets executed every time the FastCGI script gets called.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="4248"></A>\r
+ <P>\r
+ A response loop typically has the following format:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4255">while (FCGI::accept >= 0) {\r
+</A>\r
+<A NAME="4256"># body of response loop\r
+</A>\r
+<A NAME="4257">}\r
+</A>\r
+</PRE>\r
+ <A NAME="4258"></A>\r
+ <P>\r
+ The <CODE>accept</CODE> call returns 0 whenever a client requests the FastCGI script. Otherwise, the\r
+ <CODE>accept</CODE> call returns -1.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Example: TinyFastCGI\r
+ </H1>\r
+ <A NAME="4588"></A>\r
+ <P>\r
+ Here is a simple example of a FastCGI application written in Perl:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4589"></A>\r
+#!fcgi-savvy-perl\r
+\r
+use FCGI; # Imports the library; required line\r
+\r
+# Initialization code\r
+\r
+$cnt = 0;\r
+\r
+# Response loop\r
+\r
+while (FCGI::accept >= 0) {\r
+ print "Content-type: text/html\r\n\r\n";\r
+ print "<head>\n<title>FastCGI Demo Page (perl)</title>\n</head>\n";\r
+ print "<h1>FastCGI Demo Page (perl)</h1>\n";\r
+ print "This is coming from a FastCGI server.\n<BR>\n";\r
+ print "Running on <EM>$ENV{SERVER_NAME}</EM> to <EM>$ENV{REMOTE_HOST}</EM>\n<BR>\n";\r
+ $cnt++;\r
+ print "This is connection number $cnt\n";\r
+}\r
+</PRE>\r
+ <P>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch2c.htm">[Prev]</A> <A HREF="ch4tcl.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:18 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide - Chapter 4, Developing FastCGI Applications in Tcl</title></head>
-<body bgcolor=#ffffff>
-
-<a href="cover.htm">[Top]</a> <a href="ch3perl.htm">[Prev]</a> <a href="apaman.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="3659">
-<center><h1>4 Developing FastCGI <br>Applications in Tcl</h1></center>
-</a><a name="4835"></a>
-This chapter explains how to code FastCGI applications in Tcl. Prior to creating a FastCGI application, you must have a FastCGI-savvy version of the Tcl interpreter. Open Market develops Tcl binaries for popular platforms and makes them available with our developer's kit. <p>
-<a name="4943"></a>
-The FastCGI-savvy binaries are extensions of standard Tcl, and are intended to replace your existing Tcl installation. There is no need to maintain two versions of Tcl: the version that we supply will work fine when invoked from a shell or a CGI program. There are also directions in the developer's kit for how to make your own FastCGI-savvy Tcl, if you need a version for some platform that we don't supply.<p>
-<a name="4221"></a>
-In many cases, you can convert a Tcl script from CGI to FastCGI by adding a few lines of code to an existing script. For more complex scripts, you may also need to rearrange some existing code. <p>
-<a name="4222">
-<h1> Getting Started</h1>
-</a><a name="4223"></a>
-The first line of any Tcl script typically specifies the pathname of the Tcl interpreter itself. You must specify the pathname of a FastCGI-savvy Tcl. <p>
-<a name="4226"></a>
-Then, you have to divide FastCGI scripts into the following two sections:<p>
-<ul><a name="4227"></a>
-<li>Initialization section, which is executed only once.
-<a name="4228"></a>
-<li>Response loop section, which gets executed every time the FastCGI script gets called.
-</ul><a name="4229"></a>
-A response loop typically has the following format:<p>
-<pre><a name="4923">
-while {[FCGI_Accept] >= 0 } {
-</a>
-<a name="4925">
-# body of response loop
-</a>
-<a name="4367">
-}
-</a>
-</pre><a name="4233"></a>
-The <code>FCGI_Accept</code> call returns 0 whenever a client requests the FastCGI script. Otherwise, the <code>FCGI_Accept</code> call returns -1. <p>
-<a name="4853">
-<h1> Example: TinyFastCGI</h1>
-</a><a name="4343"></a>
-Here is a simple example of a FastCGI application written in Tcl:<p>
-<pre><a name="4344"></a>
-#!fcgi-savvy-tcl
-
-set count 0
-
-# Response Loop
-while {[FCGI_Accept] >= 0 } {
- incr count
- puts -nonewline "Content-type: text/html\r\n\r\n"
- puts "<title>FastCGI Hello! (Tcl)</title>"
- puts "<h1>FastCGI Hello! (Tcl)</h1>"
- puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
-}
-</pre>
-<p>
-
-<hr><br>
-
-<a href="cover.htm">[Top]</a> <a href="ch3perl.htm">[Prev]</a> <a href="apaman.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:00:19 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide - Chapter 4, Developing FastCGI Applications in Tcl\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+ li.c2 {list-style: none}\r
+ div.c1 {text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch3perl.htm">[Prev]</A> <A HREF="apaman.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <A NAME="3659"></A>\r
+ <DIV CLASS="c1">\r
+ <H1>\r
+ 4 Developing FastCGI<BR>\r
+ Applications in Tcl\r
+ </H1>\r
+ </DIV>\r
+ <A NAME="4835"></A>\r
+ <P>\r
+ This chapter explains how to code FastCGI applications in Tcl. Prior to creating a FastCGI application, you\r
+ must have a FastCGI-savvy version of the Tcl interpreter. Open Market develops Tcl binaries for popular\r
+ platforms and makes them available with our developer's kit.\r
+ </P>\r
+ <P>\r
+ <A NAME="4943"></A> The FastCGI-savvy binaries are extensions of standard Tcl, and are intended to replace\r
+ your existing Tcl installation. There is no need to maintain two versions of Tcl: the version that we supply\r
+ will work fine when invoked from a shell or a CGI program. There are also directions in the developer's\r
+ kit for how to make your own FastCGI-savvy Tcl, if you need a version for some platform that we don't\r
+ supply.\r
+ </P>\r
+ <P>\r
+ <A NAME="4221"></A> In many cases, you can convert a Tcl script from CGI to FastCGI by adding a few lines of\r
+ code to an existing script. For more complex scripts, you may also need to rearrange some existing code.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Getting Started\r
+ </H1>\r
+ <A NAME="4223"></A>\r
+ <P>\r
+ The first line of any Tcl script typically specifies the pathname of the Tcl interpreter itself. You must\r
+ specify the pathname of a FastCGI-savvy Tcl.\r
+ </P>\r
+ <P>\r
+ <A NAME="4226"></A> Then, you have to divide FastCGI scripts into the following two sections:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <UL>\r
+ <LI CLASS="c2">\r
+ <A NAME="4227"></A>\r
+ </LI>\r
+ <LI>\r
+ Initialization section, which is executed only once. <A NAME="4228"></A>\r
+ </LI>\r
+ <LI>\r
+ Response loop section, which gets executed every time the FastCGI script gets called.\r
+ </LI>\r
+ </UL>\r
+ <A NAME="4229"></A>\r
+ <P>\r
+ A response loop typically has the following format:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4923">while {[FCGI_Accept] >= 0 } {\r
+</A>\r
+<A NAME="4925"># body of response loop\r
+</A>\r
+<A NAME="4367">}\r
+</A>\r
+</PRE>\r
+ <A NAME="4233"></A>\r
+ <P>\r
+ The <CODE>FCGI_Accept</CODE> call returns 0 whenever a client requests the FastCGI script. Otherwise, the\r
+ <CODE>FCGI_Accept</CODE> call returns -1.\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ Example: TinyFastCGI\r
+ </H1>\r
+ <A NAME="4343"></A>\r
+ <P>\r
+ Here is a simple example of a FastCGI application written in Tcl:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+<A NAME="4344"></A>\r
+#!fcgi-savvy-tcl\r
+\r
+set count 0\r
+\r
+# Response Loop\r
+while {[FCGI_Accept] >= 0 } {\r
+ incr count\r
+ puts -nonewline "Content-type: text/html\r\n\r\n"\r
+ puts "<title>FastCGI Hello! (Tcl)</title>"\r
+ puts "<h1>FastCGI Hello! (Tcl)</h1>"\r
+ puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"\r
+}\r
+</PRE>\r
+ <P>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <A HREF="cover.htm">[Top]</A> <A HREF="ch3perl.htm">[Prev]</A> <A HREF="apaman.htm">[Next]</A> <A HREF=\r
+ "ap_guida.htm">[Bottom]</A> \r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:00:19 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<html><head><title>FastCGI Programmer's Guide</title></head>
-<body bgcolor=#ffffff>
-
-[Top] [Prev] <a href="ap_guide.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-<a name="336">
-<h1> Open Market FastCGI 1.0</h1>
-</a><a name="94"></a>
- Open Market, Inc.<br>245 First Street, Cambridge, MA 02142<br>T: 617-621-9500 F: 617-252-3492<p>
-<a name="238">
-<h1> <img src="covera.gif"></h1>
-</a><a name="347">
-<h2> Programmer's Guide</h2>
-</a><a name="351">
-<h2> April 15, 1996 s p/n 42-10530-001 Rev. A</h2>
-</a>
-<hr><br>
-
-<a name="249"></a>
- OPEN MARKET, INC., PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. In no event shall Open Market be liable for any loss of profits, loss of business, loss of use of data, interruption of business, or for indirect, special, incidental, or consequential damages of any kind, even if Open Market has been advised of the possibility of such damages arising from any defect or error in this publication.<p>
-<a name="256"></a>
- <p>
-<a name="260"></a>
- Open Market may revise this publication from time to time without notice. Some states or jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.<p>
-<a name="261"></a>
- <p>
-<a name="265"></a>
- Copyright © 1996 Open Market, Inc.<p>
-<a name="266"></a>
- <p>
-<a name="267"></a>
- All rights reserved.<p>
-<a name="268"></a>
- <p>
-<a name="269"></a>
- <em>Alpha/OSF</em> is a trademark of Digital Equipment Corporation.<p>
-<a name="278"></a>
- <em>Digital UNIX</em> is a trademark of Digital Equipment Corporation.<br><em>BSD/386</em> is a trademark of Berkeley Software Design, Inc.<br><em>BSD/OS</em> is a trademark of Berkeley Software Design, Inc.<p>
-<a name="308"></a>
- <em>Great Circle</em> is a trademark of Geodesic Systems, Inc.<br><em>HP-UX</em> is a trademark of Hewlett-Packard Co., Inc.<br><em>IBM AIX</em> is a trademark of International Business Machines, Inc.<br><em>Word</em> is a trademark of Microsoft Corporation.<br><em>Netscape</em> is a trademark of Netscape Communications Company.<br><em>PostScript</em> is a trademark of Adobe Systems Inc.<p>
-<a name="307"></a>
- <em>Purify</em> is a trademark of Pure Software, Inc.<br><em>SecureWeb</em> is a trademark of Terisa Systems, Inc.<br><em>HylaFAX</em> is a trademark of Silicon Graphics, Inc.<br><em>SGI IRIX</em> is a trademark of Silicon Graphics, Inc.<br><em>Solaris</em> is a trademark of Sun Microsystems, Inc.<br><em>SunOS</em> is a trademark of Sun Microsystems, Inc.<br><em>UNIX</em> is a trademark of UNIX Systems Laboratories, Inc.<p>
-<a name="270"></a>
- <p>
-<a name="271"></a>
- Any other trademarks and product names used herein may be the trademarks of their respective companies.<p>
-
-
-[Top] [Prev] <a href="ap_guide.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
-<hr><br>
-
-
-<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
-<!-- -->
-<!-- For more information on how this document, and how the rest of -->
-<!-- this server was created, email yourEmail@xyzcorp.com -->
-<!-- -->
-<!-- Last updated: 04/15/96 08:03:01 -->
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI Programmer's Guide\r
+ </TITLE>\r
+<STYLE TYPE="text/css">\r
+ body {\r
+ background-color: #ffffff;\r
+ }\r
+</STYLE>\r
+ </HEAD>\r
+ <BODY>\r
+ <P>\r
+ [Top] [Prev] <A HREF="ap_guide.htm">[Next]</A> <A HREF="ap_guida.htm">[Bottom]</A>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ \r
+ <H1>\r
+ Open Market FastCGI 1.0\r
+ </H1>\r
+ <A NAME="94"></A>\r
+ <P>\r
+ Open Market, Inc.<BR>\r
+ 245 First Street, Cambridge, MA 02142<BR>\r
+ T: 617-621-9500 F: 617-252-3492\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+ <H1>\r
+ <IMG ALT="error-file:TidyOut.log" SRC="covera.gif">\r
+ </H1>\r
+ <H2>\r
+ Programmer's Guide\r
+ </H2>\r
+ <H2>\r
+ April 15, 1996 s p/n 42-10530-001 Rev. A\r
+ </H2>\r
+ <HR>\r
+ <BR>\r
+ <A NAME="249"></A>\r
+ <P>\r
+ OPEN MARKET, INC., PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR\r
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR\r
+ PURPOSE. In no event shall Open Market be liable for any loss of profits, loss of business, loss of use of\r
+ data, interruption of business, or for indirect, special, incidental, or consequential damages of any kind,\r
+ even if Open Market has been advised of the possibility of such damages arising from any defect or error in\r
+ this publication.\r
+ </P>\r
+ <P>\r
+ <A NAME="256"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="260"></A> Open Market may revise this publication from time to time without notice. Some states or\r
+ jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore,\r
+ this statement may not apply to you.\r
+ </P>\r
+ <P>\r
+ <A NAME="261"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="265"></A> Copyright © 1996 Open Market, Inc.\r
+ </P>\r
+ <P>\r
+ <A NAME="266"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="267"></A> All rights reserved.\r
+ </P>\r
+ <P>\r
+ <A NAME="268"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="269"></A> <EM>Alpha/OSF</EM> is a trademark of Digital Equipment Corporation.\r
+ </P>\r
+ <P>\r
+ <A NAME="278"></A> <EM>Digital UNIX</EM> is a trademark of Digital Equipment Corporation.<BR>\r
+ <EM>BSD/386</EM> is a trademark of Berkeley Software Design, Inc.<BR>\r
+ <EM>BSD/OS</EM> is a trademark of Berkeley Software Design, Inc.\r
+ </P>\r
+ <P>\r
+ <A NAME="308"></A> <EM>Great Circle</EM> is a trademark of Geodesic Systems, Inc.<BR>\r
+ <EM>HP-UX</EM> is a trademark of Hewlett-Packard Co., Inc.<BR>\r
+ <EM>IBM AIX</EM> is a trademark of International Business Machines, Inc.<BR>\r
+ <EM>Word</EM> is a trademark of Microsoft Corporation.<BR>\r
+ <EM>Netscape</EM> is a trademark of Netscape Communications Company.<BR>\r
+ <EM>PostScript</EM> is a trademark of Adobe Systems Inc.\r
+ </P>\r
+ <P>\r
+ <A NAME="307"></A> <EM>Purify</EM> is a trademark of Pure Software, Inc.<BR>\r
+ <EM>SecureWeb</EM> is a trademark of Terisa Systems, Inc.<BR>\r
+ <EM>HylaFAX</EM> is a trademark of Silicon Graphics, Inc.<BR>\r
+ <EM>SGI IRIX</EM> is a trademark of Silicon Graphics, Inc.<BR>\r
+ <EM>Solaris</EM> is a trademark of Sun Microsystems, Inc.<BR>\r
+ <EM>SunOS</EM> is a trademark of Sun Microsystems, Inc.<BR>\r
+ <EM>UNIX</EM> is a trademark of UNIX Systems Laboratories, Inc.\r
+ </P>\r
+ <P>\r
+ <A NAME="270"></A>\r
+ </P>\r
+ <P>\r
+ <A NAME="271"></A> Any other trademarks and product names used herein may be the trademarks of their\r
+ respective companies.\r
+ </P>\r
+ <P>\r
+ [Top] [Prev] <A HREF="ap_guide.htm">[Next]</A> <A HREF="ap_guida.htm">[Bottom]</A>\r
+ </P>\r
+ <HR>\r
+ <BR>\r
+ <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
+ <!-- -->\r
+ <!-- For more information on how this document, and how the rest of -->\r
+ <!-- this server was created, email yourEmail@xyzcorp.com -->\r
+ <!-- -->\r
+ <!-- Last updated: 04/15/96 08:03:01 -->\r
+ </BODY>\r
+</HTML>\r
+\r
-<HTML>
-
-
-
-<HEAD>
-
-
-
-<TITLE>FastCGI</TITLE>
-
-
-
-<META NAME="GENERATOR" CONTENT="Internet Assistant for Microsoft Word 2.0z">
-
-</HEAD>
-
-<!--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. -->
-<!-- $Id: fastcgi.htm,v 1.2 2001/05/14 13:00:32 robs Exp $ -->
-
-<BODY>
-
-
-
-<P>
-
-Open Market, Inc.
-
-<P>
-
-<CENTER><FONT SIZE=4 COLOR=#FFFFFF FACE="Impact">Technical White
-
-Paper<BR>
-
-</FONT></CENTER>
-
-<H1>FastCGI:<BR>
-
-A High-Performance Web Server Interface</H1>
-
-
-
-<P>
-
-April 1996<!--Please send comments to:-->
-
-<HR>
-
-<!-- payne@openmarket.com-->
-
-<H2>1. Introduction</H2>
-
-
-
-<P>
-
-The surge in the use of the Web by business has created
-
-a tremendous need for server extension applications that create
-
-dynamic content. These are the applications that will allow businesses
-
-to deliver products, services, and messages whose shape and content
-
-are in part determined by the interaction with, and knowledge
-
-of, the customers to which they are delivered.
-
-<P>
-
-This important movement away from static Web content
-
-is pushing the limits and exposing the weaknesses of the environment
-
-in which these applications are currently bound: CGI (Common Gateway
-
-Interface). Most importantly it does not offer the performance
-
-these applications require. A new communication infrastructure
-
-is needed to connect Web servers with these new applications.
-
-This is what led Open Market to develop FastCGI.
-
-<P>
-
-FastCGI is a fast, open, and secure Web server interface
-
-that solves the performance problems inherent in CGI, without
-
-introducing the overhead and complexity of proprietary APIs (Application
-
-Programming Interfaces).
-
-<P>
-
-This paper assumes that the reader has basic familiarity
-
-with Web technology and developing Web applications.
-
-<H3>Common Gateway Interface</H3>
-
-
-
-<P>
-
-The de facto standard interface for Web server applications
-
-is CGI, which was first implemented in the NCSA server. CGI has
-
-many benefits:
-
-<UL>
-
-<LI><B>Simplicity. </B><FONT>It is
-
-easy to understand.</FONT>
-
-<LI><B>Language independence.</B>
-
-CGI applications can be written in nearly any language.
-
-<LI><B>Process isolation.</B>
-
-Since applications run in separate processes, buggy applications
-
-cannot crash the Web server or access the server's private internal
-
-state.
-
-<LI><B>Open standard.</B> Some
-
-form of CGI has been implemented on every Web server.
-
-<LI><B>Architecture independence.</B>
-
-CGI is not tied to any particular server architecture (single
-
-threaded, multi-threaded, etc.).
-
-</UL>
-
-
-
-<P>
-
-CGI also has some significant drawbacks. The leading
-
-problem is performance: Since a new process is created for each
-
-request and thrown away when the request is done, efficiency is
-
-poor.
-
-<P>
-
-CGI also has limited functionality: It only supports
-
-a simple "responder" role, where the application generates
-
-the response that is returned to the client. CGI programs can't
-
-link into other stages of Web server request processing, such
-
-as authorization and logging.
-
-<H3>Server APIs</H3>
-
-
-
-<P>
-
-In response to the performance problems for CGI,
-
-several vendors have developed APIs for their servers. The two
-
-most notable are NSAPI from Netscape and ISAPI from Microsoft.
-
- The freely available Apache server also has an API.
-
-<P>
-
-Applications linked into the server API may be significantly
-
-faster than CGI programs. The CGI startup/initialization problem
-
-is improved, because the application runs in the server process
-
-and is persistent across requests. Web server APIs also offer
-
-more functionality than CGI: you can write extensions that perform
-
-access control, get access to the server's log file, and link
-
-in to other stages in the server's request processing.
-
-<P>
-
-However, APIs sacrifice all of CGI's benefits. Vendor
-
-APIs have the following problems:
-
-<UL>
-
-<LI><B>Complexity.</B> Vendor
-
-APIs introduce a steep learning curve, with increased implementation
-
-and maintenance costs.
-
-<LI><B>Language dependence.</B>
-
- Applications have to be written in a language supported by the
-
-vendor API (usually C/C++). Perl, the most popular language for
-
-CGI programs, can't be used with any existing vendor API.
-
-<LI><B>No process isolation. </B><FONT>Since
-
-the applications run in the server's address space, buggy applications
-
-can corrupt the core server (or each other). A malicious or buggy
-
-application can compromise server security, and bugs in the core
-
-server can corrupt applications.</FONT>
-
-<LI><B>Proprietary.</B> Coding
-
-your application to a particular API locks you into a particular
-
-vendor's server.
-
-<LI><B>Tie-in to server architecture.</B>
-
- API applications have to share the same architecture as the server:
-
- If the Web server is multi-threaded, the application has to be
-
-thread-safe. If the Web server has single-threaded processes,
-
-multi-threaded applications don't gain any performance advantage.
-
- Also, when the vendor changes the server's architecture, the
-
-API will usually have to change, and applications will have to
-
-be adapted or rewritten.
-
-</UL>
-
-
-
-<H3>FastCGI</H3>
-
-
-
-<P>
-
-The FastCGI interface combines the best aspects of
-
-CGI and vendor APIs. Like CGI, FastCGI applications run in separate,
-
-isolated processes. FastCGI's advantages include:
-
-<UL>
-
-<LI><B>Performance.</B> FastCGI
-
-processes are persistent-they are reused to handle multiple requests.
-
- This solves the CGI performance problem of creating new processes
-
-for each request.
-
-<LI><B>Simplicity, with easy migration from CGI.</B>
-
- The FastCGI application library (described on page 9) simplifies
-
-the migration of existing CGI applications. Applications built
-
-with the application library can also run as CGI programs, for
-
-backward compatibility with old Web servers.
-
-<LI><B>Language independence.</B>
-
-Like CGI, FastCGI applications can be written in any language,
-
-not just languages supported by the vendor API.
-
-<LI><B>Process isolation.</B>
-
-A buggy FastCGI application cannot crash or corrupt the core server
-
-or other applications. A malicious FastCGI application cannot
-
-steal any secrets (such as session keys for encryption) from the
-
-Web server.
-
-<LI><B>Non-proprietary.</B>
-
-FastCGI is supported in all of Open Market's server products,
-
-and support is under development for other Web servers, including
-
-the freely available Apache and NCSA servers, as well as commercial
-
-servers from Microsoft and Netscape.
-
-<LI><B>Architecture independence.</B>
-
- The FastCGI interface is not tied to a particular server architecture.
-
- Any Web server can implement the FastCGI interface. Also, FastCGI
-
-does not impose any architecture on the application: applications
-
-can be single or multi-threaded, regardless of the threading architecture
-
-of the Web server.
-
-<LI><B>Support for distributed computing.</B>
-
- FastCGI provides the ability to run applications remotely, which
-
-is useful for distributing load and managing external Web sites.
-
-</UL>
-
-
-
-<P>
-
-The following sections describe the FastCGI interface,
-
-protocol, application library, and support in Open Market's WebServer
-
-products.
-
-<H2>2. FastCGI Interface</H2>
-
-
-
-<P>
-
-The functionality provided by the FastCGI interface
-
-is very similar to that provided by CGI. To best understand the
-
-FastCGI protocol, we review the CGI interface here. Basic CGI
-
-request processing proceeds as follows:
-
-<OL>
-
-<LI>For each request, the server creates a new process
-
-and the process initializes itself.
-
-<LI>The Web server passes the request information
-
-(such as remote host, username, HTTP headers, etc.) to the CGI
-
-program in environment variables.
-
-<LI>The Web server sends any client input (such as
-
-user-entered field values from an HTML form) to the CGI program's
-
-standard input.
-
-<LI>The CGI program writes any output to be returned
-
-to the client on standard output. Error information written to
-
-standard error is logged by the Web server.
-
-<LI>When the CGI process exits, the request is complete.
-
-</OL>
-
-
-
-<P>
-
-FastCGI is conceptually very similar to CGI, with
-
-two major differences:
-
-<UL>
-
-<LI>FastCGI processes are persistent: after finishing
-
-a request, they wait for a new request instead of exiting.
-
-<LI>Instead of using operating system environment
-
-variables and pipes, the FastCGI protocol multiplexes the environment
-
-information, standard input, output and error over a single full-duplex
-
-connection. This allows FastCGI programs to run on remote machines,
-
-using TCP connections between the Web server and the FastCGI application.
-
-</UL>
-
-
-
-<P>
-
-Request processing in a single-threaded FastCGI application
-
-proceeds as follows:
-
-<OL>
-
-<LI>The Web server creates FastCGI application processes
-
-to handle requests. The processes may be created at startup,
-
-or created on demand.
-
-<LI>The FastCGI program initializes itself, and waits
-
-for a new connection from the Web server.
-
-<LI>When a client request comes in, the Web server
-
-opens a connection to the FastCGI process. The server sends the
-
-CGI environment variable information and standard input over the
-
-connection.
-
-<LI>The FastCGI process sends the standard output
-
-and error information back to the server over the same connection.
-
-<LI>When the FastCGI process closes the connection,
-
-the request is complete. The FastCGI process then waits for another
-
-connection from the Web server.
-
-</OL>
-
-
-
-<P>
-
-FastCGI applications can run locally (on the same
-
-machine as the Web server) or remotely. For local applications,
-
-the server uses a full-duplex pipe to connect to the FastCGI application
-
-process. For remote applications, the server uses a TCP connection.
-
-<P>
-
-FastCGI applications can be single-threaded or multi-threaded.
-
- For single threaded applications, the Web server maintains a
-
-pool of processes (if the application is running locally) to
-
-handle client requests. The size of the pool is user configurable.
-
- Multi-threaded FastCGI applications may accept multiple connections
-
-from the Web server and handle them simultaneously in a single
-
-process. (For example, Java's built-in multi-threading, garbage
-
-collection, synchronization primitives, and platform independence
-
-make it a natural implementation language for multi-threaded FastCGI
-
-applications.)
-
-<H3>Remote FastCGI</H3>
-
-
-
-<P>
-
-FastCGI's ability to run applications remotely (over
-
-a TCP connection) provides some major benefits. These benefits
-
-are described in this section, along with some of the security
-
-issues that affect remote FastCGI applications.
-
-<H4>FastCGI with Firewalls</H4>
-
-
-
-<P>
-
-Applications that run on organizational (external) Web servers
-
-and depend on internal databases can be a challenge to administer.
-
-Figure 1 shows a typical organization, with an external Web server,
-
-a firewall restricting access to the internal network, and internal
-
-databases and applications.
-
-<P>
-
-<CENTER><IMG SRC="img00001.gif"><A NAME="_Ref352505891">Figure
-
-1</A></CENTER>
-
-<P>
-
-With CGI and vendor APIs, the application has to run on the Web
-
-server machine. This means the server administrator has to replicate
-
-the necessary database information onto the system hosting the
-
-Web server (which may be difficult to do in an automated way without
-
-compromising firewall security). Or, the administrator may build
-
-a "bridge" that allows access through the Web server
-
-to internal databases and applications (which is effectively re-inventing
-
-remote FastCGI).
-
-<P>
-
-With remote FastCGI, the applications can run on the internal
-
-network, simplifying the administrator's job. When used with
-
-appropriate firewall configuration and auditing, this approach
-
-provides a secure, high-performance, scalable way to bring internal
-
-applications and data to the external network.
-
-<H4>Load Distribution</H4>
-
-
-
-<P>
-
-For resource-intensive CGI and API applications, the Web server
-
-machine quickly becomes the bottleneck for overall throughput.
-
-The usual way to solve this performance problem is to buy a bigger,
-
-faster Web server machine, or to partition the Web site across
-
-several Web servers.
-
-<P>
-
-With remote FastCGI, the resource-intensive applications can be
-
-moved off the Web server machine, giving the server administrator
-
-additional flexibility in configuring the Web server. The administrator
-
-can configure FastCGI applications "behind the scenes"
-
-without having to change any content links or the external view
-
-of the Web site. The administrator can use several smaller, inexpensive
-
-server machines for applications, and can tailor each machine
-
-to the application it is hosting.
-
-<H4>Security Issues with Remote FastCGI</H4>
-
-
-
-<P>
-
-The two security issues with remote FastCGI connections are authentication
-
-and privacy. FastCGI applications should only accept connections
-
-from Web servers that they trust (the application library includes
-
-support for IP address validation). Future versions of the protocol
-
-will include support for applications authenticating Web servers,
-
-as well as support for running remote connections over secure
-
-transport protocols such as SSL or PCT.<!--This pargraph needs to be made stronger, going into the issues in a little more detail.-->
-
-
-
-<H3>The FastCGI Protocol</H3>
-
-
-
-<P>
-
-This section offers a brief introduction to the protocol
-
-used on the connection between the Web server and FastCGI application.
-
- Most application developers will use the FastCGI application
-
-library and won't have to worry about the protocol details. However,
-
-specialized applications are free to implement the FastCGI protocol
-
-directly.
-
-<P>
-
-FastCGI uses a simple packet record format on the
-
-connection between the application and the Web server. The same
-
-record format is used in both directions and is outlined in Figure 2.
-
-<P>
-
-<CENTER><IMG SRC="img00002.gif"><A NAME="_Ref352404075">Figure
-
-2</A></CENTER>
-
-<P>
-
-The protocol version field specifies the version
-
-of the FastCGI protocol that is in use. The type field specifies
-
-the type of the record (described in the following section).
-
-The request ID identifies this record to a particular request,
-
-allowing multiple requests to be multiplexed over a single connection.
-
- The data length field specifies the number of data bytes that
-
-follow.
-
-<P>
-
-The different FastCGI packet types are:
-
-<TABLE>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_PARAMS</FONT></TT>
-
-</TD><TD WIDTH=228>Used for sending name/value pairs (CGI environment variables) from the Web server to the application.
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDIN</FONT></TT>
-
-</TD><TD WIDTH=228>Used for sending the standard input from the Web server to the application.
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_DATA</FONT></TT>
-
-</TD><TD WIDTH=228>Used for sending filter data to the application (for more information, see the filter role described on page 7.)
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDOUT</FONT></TT>
-
-</TD><TD WIDTH=228>Used to send standard output from the application to the Web server.
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDERR</FONT></TT>
-
-</TD><TD WIDTH=228>Used to send standard error information from the application to the Web server.
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_END_REQUEST</FONT></TT>
-
-</TD><TD WIDTH=228>Ends the request (can be sent by either the server or the application).
-
-</TD></TR>
-
-
-
-</TABLE>
-
-
-
-<P>
-
-
-
-<P>
-
-For complete protocol details, see the <I>FastCGI Protocol Specification</I>,
-
-available from the Web site listed at the end of this paper.
-
-<H2>3. Application Roles</H2>
-
-
-
-<P>
-
-A major problem with CGI is its limited functionality:
-
- CGI programs can only provide simple responses to requests.
-
-FastCGI provides expanded functionality with support for three
-
-different application "roles":
-
-<UL>
-
-<LI><B>Responder.</B> This is
-
-the basic FastCGI role, and corresponds to the simple functionality
-
-offered by CGI today.
-
-<LI><B>Filter.</B> The FastCGI
-
-application filters the requested Web server file before sending
-
-it to the client.
-
-<LI><B>Authorizer.</B> The FastCGI
-
-program performs an access control decision for the request (such
-
-as performing a username/password database lookup).
-
-</UL>
-
-
-
-<P>
-
-Other roles will be defined in the future. For instance,
-
-a "logger" role would be useful, where the FastCGI program
-
-would receive the server's log entries for real-time processing
-
-and analysis.
-
-<P>
-
-The roles are described in more detail in the following
-
-sections.
-
-<H3>Responder Role</H3>
-
-
-
-<P>
-
-FastCGI's Responder role is identical to the functionality
-
-provided by CGI today. When a request comes into the server,
-
-the FastCGI program generates the response that's returned to
-
-the client (typically an HTML page).
-
-<H3><A NAME="_Ref352404524">Filter Role</A></H3>
-
-
-
-<P>
-
-The Filter role allows a FastCGI application to process
-
-a requested file before it is returned to the client.
-
-<P>
-
-Let's assume that the Web server is configured so
-
-that all files with the .<TT><FONT FACE="Courier">sgml
-
-</FONT></TT>extension are processed by a SGML-to-HTML
-
-FastCGI filter application, and the user accesses the following
-
-URL:
-
-<P>
-
- <TT><FONT FACE="Courier">/document.sgml</FONT></TT>
-
-<P>
-
-After the Web server makes an access control decision
-
-and maps this URL to a content file, it invokes the FastCGI filter
-
-application with this file available as input. The FastCGI program's
-
-HTML output is sent back to the client, just as in the responder
-
-role. The process is outlined in Figure 3.
-
-<P>
-
-<CENTER><IMG SRC="img00003.gif"><A NAME="_Ref352560526">Figure
-
-3</A></CENTER>
-
-<P>
-
-Filter applications can significantly improve performance
-
-by caching filter results (the server provides the modification
-
-time in the request information so that applications can flush
-
-the cache when the server file has been modified).
-
-<P>
-
-The Filter role is useful for:
-
-<UL>
-
-<LI>On-the-fly format conversions
-
-<LI>Dynamic documents (such as documents with embedded
-
-SQL queries, or dynamic advertisement insertion)
-
-<LI>Applying a standard template: headers, footers,
-
-and backgrounds
-
-</UL>
-
-
-
-<H3>Authorizer Role</H3>
-
-
-
-<P>
-
-The Authorizer role allows a FastCGI application
-
-to make an access control decision for a request. The FastCGI
-
-application is invoked with all of the request information, just
-
-as in the Responder role. If the authorizer application generates
-
-a "200 OK" HTTP result, the Web server assumes that
-
-access is allowed and proceeds with the request. (The Web server
-
-may process other access checks, including other FastCGI authorizers,
-
-before access is ultimately allowed.) If the application generates
-
-any other response, that response is returned to the client and
-
-the request is ended. The response can be any valid HTTP response,
-
-including "Access Denied" or "Redirect".
-
-<P>
-
-The Authorizer role is useful for:
-
-<UL>
-
-<LI>Access control based on username and password,
-
-where the user information is looked up in an external database.
-
-<LI>Complex access policies, such as time-of-day
-
-based access.
-
-<LI>Smart-card challenge/response authentication.
-
-<LI>Dynamic redirects, where the user is sent to
-
-different pages based on the request profile.
-
-</UL>
-
-
-
-<H2><A NAME="_Ref352251764">4. FastCGI Application Library</A></H2>
-
-
-
-<P>
-
-Open Market has developed a FastCGI application library
-
-that implements the FastCGI protocol (hiding the protocol details
-
-from the developer). This library makes implementing FastCGI programs
-
-as easy as writing CGI applications.
-
-<P>
-
-The application library provides a replacement for
-
-the C language standard I/O (stdio) routines, such as <TT><FONT FACE="Courier">printf()</FONT></TT>
-
-and <TT><FONT FACE="Courier">gets()</FONT></TT>.
-
- The library converts references to standard input, standard output,
-
-and standard error to the FastCGI protocol. References to other
-
-files "fall through" to the underlying operating system
-
-standard I/O routines.
-
-<P>
-
-This approach has several benefits:
-
-<UL>
-
-<LI>Developers don't have to learn a new API to develop
-
-FastCGI applications.
-
-<LI>Existing CGI programs can be migrated with minimal
-
-source changes (CGI migration is described in more detail in the
-
-following section).
-
-<LI>FastCGI interpreters for Perl, Tcl, and other
-
-interpreted languages can be built without modifying the interpreter
-
-source code.
-
-</UL>
-
-
-
-<P>
-
-Here's a simple FastCGI application:<P>
-<PRE>
- #include <fcgi_stdio.h>
-
- void main(void)
- {
- int count = 0;
- while(FCGI_Accept() >= 0) {
- printf("Content-type: text/html\r\n");
- printf("\r\n");
- printf("Hello world!<br>\r\n");
- printf("Request number %d.", count++);
- }
- exit(0);
- }
-</PRE>
-This application returns a "Hello world"
-
-HTML response to the client. It also keeps a counter of the number
-
-of times it has been accessed, displaying the value of the counter
-
-at each request.
-
-<P>
-
-The <TT>fcgi_stdio.h</TT>
-
-header file provides the FastCGI replacement routines for the
-
-C standard I/O library. The <TT>FCGI_Accept()</TT>
-
-routine accepts a new request from the Web server.
-
-<H3>Migrating Existing CGI Programs</H3>
-
-
-
-<P>
-
-The application library was designed to make migration
-
-of existing CGI programs as simple as possible. Many applications
-
-can be converted by adding a loop around the main request processing
-
-code and recompiling with the FastCGI application library. FastCGI
-
-applications have the following structure, with an initialization
-
-section and a request processing loop:<p>
-
-
-<I>Initialize application;<BR>
-
-</I><TT>while(FCGI_Accept() >= 0) {</TT><BR>
-
- <I>Process request</I>;<BR>
-
-<TT>}</TT>
-
-<P>
-
-To ease migration to FastCGI, executables built with
-
-the application library can run as either CGI or FastCGI programs,
-
-depending on how they are invoked. The library detects the execution
-
-environment and automatically selects FastCGI or regular I/O routines,
-
-as appropriate.
-
-<P>
-
-After migration, developers can clean up their FastCGI
-
-applications for best performance:
-
-<UL>
-
-<LI>Fix any resource leaks. Many CGI programs do
-
-not attempt to manage memory or close files, because they assume
-
-the world is going to be cleaned up when they exit. (If you don't
-
-want to clean up your program, you can just have your process
-
-assume that it is leaking memory and exit after processing some
-
-fixed number of requests.) Purify from Pure Software is one of
-
-a number of excellent tools for finding leaks and other memory
-
-use problems.
-
-<LI>Fix any problems with retained application state.
-
- The application must ensure that any state that it creates in
-
-processing one request has no unintended effects on later requests.
-
-
-
-<LI>Collapse functionality. A common practice with
-
-CGI applications is to implement many small programs, with one
-
-function per program. CGI encourages this, because smaller programs
-
-load faster. With FastCGI, it's better to have related functionality
-
-in a single executable, so there are fewer processes to manage
-
-and applications can take advantage of sharing cached information
-
-across functions.
-
-</UL>
-
-
-
-<P>
-
-Applications written in Perl, Tcl, and other scripting
-
-languages can be migrated by using a language interpreter built
-
-with the application library. FastCGI-integrated Tcl and Perl
-
-interpreters for popular Unix platforms are available from Open
-
-Market. The interpreters are backward-compatible: They can run
-
-standard Tcl and Perl applications.
-
-<H2>5. FastCGI in the Open Market WebServer</H2>
-
-
-
-<P>
-
-This section describes the FastCGI support in the
-
-following Open Market server products:
-
-<UL>
-
-<LI>Open Market WebServer V2.0
-
-<LI>Open Market Secure WebServer V2.0
-
-<LI>Open Market Secure WebServer (Global) V2.0
-
-</UL>
-
-
-
-<P>
-
-For more information about FastCGI support, see
-
-the <I>Open Market WebServer Installation and Configuration Guide</I>.
-
-<H3>Server Configuration</H3>
-
-
-
-<P>
-
-FastCGI applications are configured with the server's
-
-configuration file. Configuration has two parts.
-
-<P>
-
-First, the server administrator defines an <I>application
-
-class</I>. For local applications, the application class specifies
-
-the details of running the FastCGI application, such as:
-
-<UL>
-
-<LI>The pathname of the application executable.
-
-<LI>Any arguments and environment variables to pass
-
-to the process at startup.
-
-<LI>The number of processes to run.
-
-</UL>
-
-
-
-<P>
-
-For remote applications, the class configuration
-
-information includes the host and TCP port to connect to. The
-
-Web server assumes that the FastCGI application has been started
-
-on the remote host. If a request comes in and the server can't
-
-connect to the FastCGI TCP port, the server logs an error and
-
-returns an error page to the client.
-
-<P>
-
-The second configuration step is mapping the application
-
-class to a role:
-
-<UL>
-
-<LI>For responder roles, the administrator configures
-
-some part of the URL space to be handled by the FastCGI application.
-
- For example, all URLs beginning with <FONT FACE="Courier">/rollcall/</FONT>
-
-might be handled by the employee database application.
-
-<LI>For filter roles, the administrator configures
-
-a file extension to be handled by a filter application. For example,
-
-all files with the <FONT FACE="Courier">.sql</FONT>
-
-extension could be handled by a SQL query lookup filter.
-
-<LI>For authorizer roles, the administrator configures
-
-an authorizer application in the same manner as other access methods
-
-(hostname, username/password, etc.) A request must pass <I>all
-
-</I>access control checks (possibly including multiple FastCGI
-
-authorizers) before access is allowed.
-
-</UL>
-
-
-
-<H3>Basic FastCGI</H3>
-
-
-
-<P>
-
-To simplify migration for existing CGI programs,
-
-the WebServer provides a simple way to install new FastCGI programs
-
-without having to reconfigure the server. However, this approach
-
-doesn't offer all of the performance benefits of FastCGI application
-
-classes.
-
-<P>
-
-The WebServer treats any file with the extension
-
-<FONT FACE="Courier">.fcg</FONT> as
-
-a FastCGI application. When a request corresponds to such a file,
-
-the WebServer creates a new FastCGI process to handle the request,
-
-and shuts down the process when the request is complete (just
-
-as in CGI). In this mode of operation performance is comparable
-
-to CGI. Future versions of the WebServer will improve performance
-
-by automatically caching processes and re-using them for subsequent
-
-requests.
-
-<H3>Session Affinity</H3>
-
-
-
-<P>
-
-FastCGI programs can improve performance by caching
-
-information in the application process. For applications that
-
-require frequent but expensive operations such as validating a
-
-username/password in an external database for each request, this
-
-technique can significantly improve performance.
-
-<P>
-
-To improve the effectiveness of this technique, the
-
-WebServer implements <I>session affinity</I>. When session affinity
-
-is enabled, the WebServer arranges for all requests in a user
-
-session to be handled by the same FastCGI application process.
-
- What constitutes a "session" is configurable. The
-
-default configuration uses the WebServer's built-in session tracking
-
-facility to identify user sessions. However, the server administrator
-
-can use any part of the request information for the session affinity
-
-mapping: the URL path, the client's hostname, the username, etc.<!--Talk about applications that need to hold onto resources for the user (such as open connections to the database).-->
-
-
-
-<H2>6. FastCGI Performance Analysis</H2>
-
-
-
-<P>
-
-How fast is FastCGI? The answer depends on the application.
-
- This section contains some real FastCGI performance measurements,
-
-as well as guidelines for estimating the FastCGI speedup.
-
-<H3>FastCGI vs CGI</H3>
-
-
-
-<P>
-
-We measured the relative performance of CGI, FastCGI,
-
-and static files on the Open Market WebServer, using a simple
-
-application that generates a fixed number of output bytes. The
-
-following table shows the measured request processing time for
-
-different request types on a typical platform. The times are
-
-measured from the client perspective and include client, server,
-
-and application processing time.
-
-<TABLE BORDERCOLOR=#000000 BORDER=2>
-
-
-
-<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">Static file</FONT></CENTER>
-
-</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">21ms + 0.19ms per Kbyte</FONT></CENTER>
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">FastCGI</FONT></CENTER>
-
-</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">22ms + 0.28ms per Kbyte</FONT></CENTER>
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">CGI</FONT></CENTER>
-
-</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">59ms + 0.37ms per Kbyte</FONT></CENTER>
-
-</TD></TR>
-
-
-
-</TABLE>
-
-
-
-<P>
-
-FastCGI performance is comparable to serving static files, and
-
-significantly better than CGI (clearly showing the high overhead
-
-for process creation). Real applications have an additional time
-
-component: process initialization, which should be added to overall
-
-request processing time.
-
-<P>
-
-Let's use this data to estimate the speedup from migrating a typical
-
-database CGI application to FastCGI. Assume the application takes
-
-50ms to initialize the database connection and generates 5K of
-
-output data. Request performance can be computed as follows:
-
-<TABLE>
-
-
-
-<TR><TD WIDTH=108>CGI </TD><TD WIDTH=331>59ms + 50ms + (0.37ms)(5) = 111ms
-
-</TD></TR>
-
-
-
-<TR><TD WIDTH=108>FastCGI</TD><TD WIDTH=331>22ms + (0.28ms)(5) = 23ms
-
-</TD></TR>
-
-
-
-</TABLE>
-
-
-
-<P>
-
-In this example, FastCGI has a 5x performance advantage over CGI,
-
-mostly due to savings from not having to create and initialize
-
-new processes for each request.<!--Need to talk about FastCGI vs proprietary APIs.-->
-
-
-
-<H2>7. Conclusions</H2>
-
-
-
-<P>
-
-Today's Web business applications need a platform
-
-that's fast, open, maintainable, straightforward, stable, and
-
-secure. FastCGI's design meets these requirements, and provides
-
-for a logical extension from proven and widely deployed CGI technology.
-
- This allows developers to take advantage of FastCGI's benefits
-
-without losing their existing investment in CGI applications.<!--Need to talk about NT.-->
-
-<!--Need to give "more punch" to this conclusion: include info about uses for FastCGI (accessing legacy data in databases, access control, distributed applications, apps that have to run in multiple OS environments. -->
-
-<H2>8. For More Information</H2>
-
-
-
-<P>
-
-For more information about Open Market and our products,
-
-visit our Web site at:<FONT FACE="Courier">http://www.openmarket.com/</FONT>
-
-<P>
-
-For more information about the FastCGI protocol and
-
-the developer's kit, and the latest information about FastCGI
-
-standardization and support in other Web servers, visit the FastCGI
-
-project page at:<FONT FACE="Courier">http://www.openmarket.com/fastcgi/</FONT>
-
-</BODY>
-
-
-
-</HTML>
-
+<HTML>\r
+ <HEAD>\r
+ <TITLE>\r
+ FastCGI\r
+ </TITLE>\r
+ <META NAME="GENERATOR" CONTENT="Internet Assistant for Microsoft Word 2.0z">\r
+<STYLE TYPE="text/css">\r
+ div.c5 {font-family: Arial Narrow; font-size: 80%; text-align: center}\r
+ span.c4 {font-family: Courier}\r
+ tt.c3 {font-family: Courier}\r
+ div.c2 {text-align: center}\r
+ div.c1 {color: #FFFFFF; font-family: Impact; font-size: 120%; text-align: center}\r
+</STYLE>\r
+ </HEAD>\r
+ <!--Copyright (c) 1996 Open Market, Inc. -->\r
+ <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->\r
+ <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->\r
+ <!-- $Id: fastcgi.htm,v 1.3 2001/11/27 01:13:29 robs Exp $ -->\r
+ <BODY>\r
+ <P>\r
+ Open Market, Inc.\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <DIV CLASS="c1">\r
+ Technical White Paper<BR>\r
+ </DIV>\r
+ <H1>\r
+ FastCGI:<BR>\r
+ A High-Performance Web Server Interface\r
+ </H1>\r
+ <P>\r
+ April 1996<!--Please send comments to:-->\r
+ </P>\r
+ <HR>\r
+ <!-- payne@openmarket.com-->\r
+ <H2>\r
+ 1. Introduction\r
+ </H2>\r
+ <P>\r
+ The surge in the use of the Web by business has created a tremendous need for server extension applications\r
+ that create dynamic content. These are the applications that will allow businesses to deliver products,\r
+ services, and messages whose shape and content are in part determined by the interaction with, and knowledge\r
+ of, the customers to which they are delivered.\r
+ </P>\r
+ <P>\r
+ This important movement away from static Web content is pushing the limits and exposing the weaknesses of the\r
+ environment in which these applications are currently bound: CGI (Common Gateway Interface). Most importantly\r
+ it does not offer the performance these applications require. A new communication infrastructure is needed to\r
+ connect Web servers with these new applications. This is what led Open Market to develop FastCGI.\r
+ </P>\r
+ <P>\r
+ FastCGI is a fast, open, and secure Web server interface that solves the performance problems inherent in CGI,\r
+ without introducing the overhead and complexity of proprietary APIs (Application Programming Interfaces).\r
+ </P>\r
+ <P>\r
+ This paper assumes that the reader has basic familiarity with Web technology and developing Web applications.\r
+ </P>\r
+ <H3>\r
+ Common Gateway Interface\r
+ </H3>\r
+ <P>\r
+ The de facto standard interface for Web server applications is CGI, which was first implemented in the NCSA\r
+ server. CGI has many benefits:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ <B>Simplicity.</B> <SPAN>It is easy to understand.</SPAN>\r
+ </LI>\r
+ <LI>\r
+ <B>Language independence.</B> CGI applications can be written in nearly any language.\r
+ </LI>\r
+ <LI>\r
+ <B>Process isolation.</B> Since applications run in separate processes, buggy applications cannot crash the\r
+ Web server or access the server's private internal state.\r
+ </LI>\r
+ <LI>\r
+ <B>Open standard.</B> Some form of CGI has been implemented on every Web server.\r
+ </LI>\r
+ <LI>\r
+ <B>Architecture independence.</B> CGI is not tied to any particular server architecture (single threaded,\r
+ multi-threaded, etc.).\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ CGI also has some significant drawbacks. The leading problem is performance: Since a new process is created\r
+ for each request and thrown away when the request is done, efficiency is poor.\r
+ </P>\r
+ <P>\r
+ CGI also has limited functionality: It only supports a simple "responder" role, where the\r
+ application generates the response that is returned to the client. CGI programs can't link into other\r
+ stages of Web server request processing, such as authorization and logging.\r
+ </P>\r
+ <H3>\r
+ Server APIs\r
+ </H3>\r
+ <P>\r
+ In response to the performance problems for CGI, several vendors have developed APIs for their servers. The\r
+ two most notable are NSAPI from Netscape and ISAPI from Microsoft. The freely available Apache server also has\r
+ an API.\r
+ </P>\r
+ <P>\r
+ Applications linked into the server API may be significantly faster than CGI programs. The CGI\r
+ startup/initialization problem is improved, because the application runs in the server process and is\r
+ persistent across requests. Web server APIs also offer more functionality than CGI: you can write extensions\r
+ that perform access control, get access to the server's log file, and link in to other stages in the\r
+ server's request processing.\r
+ </P>\r
+ <P>\r
+ However, APIs sacrifice all of CGI's benefits. Vendor APIs have the following problems:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ <B>Complexity.</B> Vendor APIs introduce a steep learning curve, with increased implementation and\r
+ maintenance costs.\r
+ </LI>\r
+ <LI>\r
+ <B>Language dependence.</B> Applications have to be written in a language supported by the vendor API\r
+ (usually C/C++). Perl, the most popular language for CGI programs, can't be used with any existing\r
+ vendor API.\r
+ </LI>\r
+ <LI>\r
+ <B>No process isolation.</B> <SPAN>Since the applications run in the server's address space, buggy\r
+ applications can corrupt the core server (or each other). A malicious or buggy application can compromise\r
+ server security, and bugs in the core server can corrupt applications.</SPAN>\r
+ </LI>\r
+ <LI>\r
+ <B>Proprietary.</B> Coding your application to a particular API locks you into a particular vendor's\r
+ server.\r
+ </LI>\r
+ <LI>\r
+ <B>Tie-in to server architecture.</B> API applications have to share the same architecture as the server:\r
+ If the Web server is multi-threaded, the application has to be thread-safe. If the Web server has\r
+ single-threaded processes, multi-threaded applications don't gain any performance advantage. Also, when\r
+ the vendor changes the server's architecture, the API will usually have to change, and applications\r
+ will have to be adapted or rewritten.\r
+ </LI>\r
+ </UL>\r
+ <H3>\r
+ FastCGI\r
+ </H3>\r
+ <P>\r
+ The FastCGI interface combines the best aspects of CGI and vendor APIs. Like CGI, FastCGI applications run in\r
+ separate, isolated processes. FastCGI's advantages include:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ <B>Performance.</B> FastCGI processes are persistent-they are reused to handle multiple requests. This\r
+ solves the CGI performance problem of creating new processes for each request.\r
+ </LI>\r
+ <LI>\r
+ <B>Simplicity, with easy migration from CGI.</B> The FastCGI application library (described on page 9)\r
+ simplifies the migration of existing CGI applications. Applications built with the application library can\r
+ also run as CGI programs, for backward compatibility with old Web servers.\r
+ </LI>\r
+ <LI>\r
+ <B>Language independence.</B> Like CGI, FastCGI applications can be written in any language, not just\r
+ languages supported by the vendor API.\r
+ </LI>\r
+ <LI>\r
+ <B>Process isolation.</B> A buggy FastCGI application cannot crash or corrupt the core server or other\r
+ applications. A malicious FastCGI application cannot steal any secrets (such as session keys for\r
+ encryption) from the Web server.\r
+ </LI>\r
+ <LI>\r
+ <B>Non-proprietary.</B> FastCGI is supported in all of Open Market's server products, and support is\r
+ under development for other Web servers, including the freely available Apache and NCSA servers, as well as\r
+ commercial servers from Microsoft and Netscape.\r
+ </LI>\r
+ <LI>\r
+ <B>Architecture independence.</B> The FastCGI interface is not tied to a particular server architecture.\r
+ Any Web server can implement the FastCGI interface. Also, FastCGI does not impose any architecture on the\r
+ application: applications can be single or multi-threaded, regardless of the threading architecture of the\r
+ Web server.\r
+ </LI>\r
+ <LI>\r
+ <B>Support for distributed computing.</B> FastCGI provides the ability to run applications remotely, which\r
+ is useful for distributing load and managing external Web sites.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ The following sections describe the FastCGI interface, protocol, application library, and support in Open\r
+ Market's WebServer products.\r
+ </P>\r
+ <H2>\r
+ 2. FastCGI Interface\r
+ </H2>\r
+ <P>\r
+ The functionality provided by the FastCGI interface is very similar to that provided by CGI. To best\r
+ understand the FastCGI protocol, we review the CGI interface here. Basic CGI request processing proceeds as\r
+ follows:\r
+ </P>\r
+ <OL>\r
+ <LI>\r
+ For each request, the server creates a new process and the process initializes itself.\r
+ </LI>\r
+ <LI>\r
+ The Web server passes the request information (such as remote host, username, HTTP headers, etc.) to the\r
+ CGI program in environment variables.\r
+ </LI>\r
+ <LI>\r
+ The Web server sends any client input (such as user-entered field values from an HTML form) to the CGI\r
+ program's standard input.\r
+ </LI>\r
+ <LI>\r
+ The CGI program writes any output to be returned to the client on standard output. Error information\r
+ written to standard error is logged by the Web server.\r
+ </LI>\r
+ <LI>\r
+ When the CGI process exits, the request is complete.\r
+ </LI>\r
+ </OL>\r
+ <P>\r
+ FastCGI is conceptually very similar to CGI, with two major differences:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ FastCGI processes are persistent: after finishing a request, they wait for a new request instead of\r
+ exiting.\r
+ </LI>\r
+ <LI>\r
+ Instead of using operating system environment variables and pipes, the FastCGI protocol multiplexes the\r
+ environment information, standard input, output and error over a single full-duplex connection. This allows\r
+ FastCGI programs to run on remote machines, using TCP connections between the Web server and the FastCGI\r
+ application.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ Request processing in a single-threaded FastCGI application proceeds as follows:\r
+ </P>\r
+ <OL>\r
+ <LI>\r
+ The Web server creates FastCGI application processes to handle requests. The processes may be created at\r
+ startup, or created on demand.\r
+ </LI>\r
+ <LI>\r
+ The FastCGI program initializes itself, and waits for a new connection from the Web server.\r
+ </LI>\r
+ <LI>\r
+ When a client request comes in, the Web server opens a connection to the FastCGI process. The server sends\r
+ the CGI environment variable information and standard input over the connection.\r
+ </LI>\r
+ <LI>\r
+ The FastCGI process sends the standard output and error information back to the server over the same\r
+ connection.\r
+ </LI>\r
+ <LI>\r
+ When the FastCGI process closes the connection, the request is complete. The FastCGI process then waits for\r
+ another connection from the Web server.\r
+ </LI>\r
+ </OL>\r
+ <P>\r
+ FastCGI applications can run locally (on the same machine as the Web server) or remotely. For local\r
+ applications, the server uses a full-duplex pipe to connect to the FastCGI application process. For remote\r
+ applications, the server uses a TCP connection.\r
+ </P>\r
+ <P>\r
+ FastCGI applications can be single-threaded or multi-threaded. For single threaded applications, the Web\r
+ server maintains a pool of processes (if the application is running locally) to handle client requests. The\r
+ size of the pool is user configurable. Multi-threaded FastCGI applications may accept multiple connections\r
+ from the Web server and handle them simultaneously in a single process. (For example, Java's built-in\r
+ multi-threading, garbage collection, synchronization primitives, and platform independence make it a natural\r
+ implementation language for multi-threaded FastCGI applications.)\r
+ </P>\r
+ <H3>\r
+ Remote FastCGI\r
+ </H3>\r
+ <P>\r
+ FastCGI's ability to run applications remotely (over a TCP connection) provides some major benefits. These\r
+ benefits are described in this section, along with some of the security issues that affect remote FastCGI\r
+ applications.\r
+ </P>\r
+ <H4>\r
+ FastCGI with Firewalls\r
+ </H4>\r
+ <P>\r
+ Applications that run on organizational (external) Web servers and depend on internal databases can be a\r
+ challenge to administer. Figure 1 shows a typical organization, with an external Web server, a firewall\r
+ restricting access to the internal network, and internal databases and applications.\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <DIV CLASS="c2">\r
+ <IMG ALT="error-file:TidyOut.log" SRC="img00001.gif"><A NAME="_Ref352505891">Figure 1</A>\r
+ </DIV>\r
+ <P>\r
+ With CGI and vendor APIs, the application has to run on the Web server machine. This means the server\r
+ administrator has to replicate the necessary database information onto the system hosting the Web server\r
+ (which may be difficult to do in an automated way without compromising firewall security). Or, the\r
+ administrator may build a "bridge" that allows access through the Web server to internal databases\r
+ and applications (which is effectively re-inventing remote FastCGI).\r
+ </P>\r
+ <P>\r
+ With remote FastCGI, the applications can run on the internal network, simplifying the administrator's\r
+ job. When used with appropriate firewall configuration and auditing, this approach provides a secure,\r
+ high-performance, scalable way to bring internal applications and data to the external network.\r
+ </P>\r
+ <H4>\r
+ Load Distribution\r
+ </H4>\r
+ <P>\r
+ For resource-intensive CGI and API applications, the Web server machine quickly becomes the bottleneck for\r
+ overall throughput. The usual way to solve this performance problem is to buy a bigger, faster Web server\r
+ machine, or to partition the Web site across several Web servers.\r
+ </P>\r
+ <P>\r
+ With remote FastCGI, the resource-intensive applications can be moved off the Web server machine, giving the\r
+ server administrator additional flexibility in configuring the Web server. The administrator can configure\r
+ FastCGI applications "behind the scenes" without having to change any content links or the external\r
+ view of the Web site. The administrator can use several smaller, inexpensive server machines for applications,\r
+ and can tailor each machine to the application it is hosting.\r
+ </P>\r
+ <H4>\r
+ Security Issues with Remote FastCGI\r
+ </H4>\r
+ <P>\r
+ The two security issues with remote FastCGI connections are authentication and privacy. FastCGI applications\r
+ should only accept connections from Web servers that they trust (the application library includes support for\r
+ IP address validation). Future versions of the protocol will include support for applications authenticating\r
+ Web servers, as well as support for running remote connections over secure transport protocols such as SSL or\r
+ PCT.<!--This pargraph needs to be made stronger, going into the issues in a little more detail.-->\r
+ </P>\r
+ <H3>\r
+ The FastCGI Protocol\r
+ </H3>\r
+ <P>\r
+ This section offers a brief introduction to the protocol used on the connection between the Web server and\r
+ FastCGI application. Most application developers will use the FastCGI application library and won't have\r
+ to worry about the protocol details. However, specialized applications are free to implement the FastCGI\r
+ protocol directly.\r
+ </P>\r
+ <P>\r
+ FastCGI uses a simple packet record format on the connection between the application and the Web server. The\r
+ same record format is used in both directions and is outlined in Figure 2.\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <DIV CLASS="c2">\r
+ <IMG ALT="error-file:TidyOut.log" SRC="img00002.gif"><A NAME="_Ref352404075">Figure 2</A>\r
+ </DIV>\r
+ <P>\r
+ The protocol version field specifies the version of the FastCGI protocol that is in use. The type field\r
+ specifies the type of the record (described in the following section). The request ID identifies this record\r
+ to a particular request, allowing multiple requests to be multiplexed over a single connection. The data\r
+ length field specifies the number of data bytes that follow.\r
+ </P>\r
+ <P>\r
+ The different FastCGI packet types are:\r
+ </P>\r
+ <TABLE>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_PARAMS</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Used for sending name/value pairs (CGI environment variables) from the Web server to the application.\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_STDIN</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Used for sending the standard input from the Web server to the application.\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_DATA</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Used for sending filter data to the application (for more information, see the filter role described on\r
+ page 7.)\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_STDOUT</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Used to send standard output from the application to the Web server.\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_STDERR</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Used to send standard error information from the application to the Web server.\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="186">\r
+ <TT CLASS="c3">FCGI_END_REQUEST</TT> \r
+ </TD>\r
+ <TD WIDTH="228">\r
+ Ends the request (can be sent by either the server or the application).\r
+ </TD>\r
+ </TR>\r
+ </TABLE>\r
+ <P>\r
+ </P>\r
+ <P>\r
+ For complete protocol details, see the <I>FastCGI Protocol Specification</I>, available from the Web site\r
+ listed at the end of this paper.\r
+ </P>\r
+ <H2>\r
+ 3. Application Roles\r
+ </H2>\r
+ <P>\r
+ A major problem with CGI is its limited functionality: CGI programs can only provide simple responses to\r
+ requests. FastCGI provides expanded functionality with support for three different application\r
+ "roles":\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ <B>Responder.</B> This is the basic FastCGI role, and corresponds to the simple functionality offered by\r
+ CGI today.\r
+ </LI>\r
+ <LI>\r
+ <B>Filter.</B> The FastCGI application filters the requested Web server file before sending it to the\r
+ client.\r
+ </LI>\r
+ <LI>\r
+ <B>Authorizer.</B> The FastCGI program performs an access control decision for the request (such as\r
+ performing a username/password database lookup).\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ Other roles will be defined in the future. For instance, a "logger" role would be useful, where the\r
+ FastCGI program would receive the server's log entries for real-time processing and analysis.\r
+ </P>\r
+ <P>\r
+ The roles are described in more detail in the following sections.\r
+ </P>\r
+ <H3>\r
+ Responder Role\r
+ </H3>\r
+ <P>\r
+ FastCGI's Responder role is identical to the functionality provided by CGI today. When a request comes\r
+ into the server, the FastCGI program generates the response that's returned to the client (typically an\r
+ HTML page).\r
+ </P>\r
+ <H3>\r
+ <A NAME="_Ref352404524">Filter Role</A>\r
+ </H3>\r
+ <P>\r
+ The Filter role allows a FastCGI application to process a requested file before it is returned to the client.\r
+ </P>\r
+ <P>\r
+ Let's assume that the Web server is configured so that all files with the .<TT CLASS="c3">sgml</TT>\r
+ extension are processed by a SGML-to-HTML FastCGI filter application, and the user accesses the following URL:\r
+ </P>\r
+ <P>\r
+ <TT CLASS="c3">/document.sgml</TT>\r
+ </P>\r
+ <P>\r
+ After the Web server makes an access control decision and maps this URL to a content file, it invokes the\r
+ FastCGI filter application with this file available as input. The FastCGI program's HTML output is sent\r
+ back to the client, just as in the responder role. The process is outlined in Figure 3.\r
+ </P>\r
+ <P>\r
+ </P>\r
+ <DIV CLASS="c2">\r
+ <IMG ALT="error-file:TidyOut.log" SRC="img00003.gif"><A NAME="_Ref352560526">Figure 3</A>\r
+ </DIV>\r
+ <P>\r
+ Filter applications can significantly improve performance by caching filter results (the server provides the\r
+ modification time in the request information so that applications can flush the cache when the server file has\r
+ been modified).\r
+ </P>\r
+ <P>\r
+ The Filter role is useful for:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ On-the-fly format conversions\r
+ </LI>\r
+ <LI>\r
+ Dynamic documents (such as documents with embedded SQL queries, or dynamic advertisement insertion)\r
+ </LI>\r
+ <LI>\r
+ Applying a standard template: headers, footers, and backgrounds\r
+ </LI>\r
+ </UL>\r
+ <H3>\r
+ Authorizer Role\r
+ </H3>\r
+ <P>\r
+ The Authorizer role allows a FastCGI application to make an access control decision for a request. The FastCGI\r
+ application is invoked with all of the request information, just as in the Responder role. If the authorizer\r
+ application generates a "200 OK" HTTP result, the Web server assumes that access is allowed and\r
+ proceeds with the request. (The Web server may process other access checks, including other FastCGI\r
+ authorizers, before access is ultimately allowed.) If the application generates any other response, that\r
+ response is returned to the client and the request is ended. The response can be any valid HTTP response,\r
+ including "Access Denied" or "Redirect".\r
+ </P>\r
+ <P>\r
+ The Authorizer role is useful for:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ Access control based on username and password, where the user information is looked up in an external\r
+ database.\r
+ </LI>\r
+ <LI>\r
+ Complex access policies, such as time-of-day based access.\r
+ </LI>\r
+ <LI>\r
+ Smart-card challenge/response authentication.\r
+ </LI>\r
+ <LI>\r
+ Dynamic redirects, where the user is sent to different pages based on the request profile.\r
+ </LI>\r
+ </UL>\r
+ <H2>\r
+ <A NAME="_Ref352251764">4. FastCGI Application Library</A>\r
+ </H2>\r
+ <P>\r
+ Open Market has developed a FastCGI application library that implements the FastCGI protocol (hiding the\r
+ protocol details from the developer). This library makes implementing FastCGI programs as easy as writing CGI\r
+ applications.\r
+ </P>\r
+ <P>\r
+ The application library provides a replacement for the C language standard I/O (stdio) routines, such as <TT\r
+ CLASS="c3">printf()</TT> and <TT CLASS="c3">gets()</TT>. The library converts references to standard input,\r
+ standard output, and standard error to the FastCGI protocol. References to other files "fall\r
+ through" to the underlying operating system standard I/O routines.\r
+ </P>\r
+ <P>\r
+ This approach has several benefits:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ Developers don't have to learn a new API to develop FastCGI applications.\r
+ </LI>\r
+ <LI>\r
+ Existing CGI programs can be migrated with minimal source changes (CGI migration is described in more\r
+ detail in the following section).\r
+ </LI>\r
+ <LI>\r
+ FastCGI interpreters for Perl, Tcl, and other interpreted languages can be built without modifying the\r
+ interpreter source code.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ Here's a simple FastCGI application:\r
+ </P>\r
+ <BR>\r
+ <BR>\r
+<PRE>\r
+ #include <fcgi_stdio.h>\r
+\r
+ void main(void)\r
+ {\r
+ int count = 0;\r
+ while(FCGI_Accept() >= 0) {\r
+ printf("Content-type: text/html\r\n");\r
+ printf("\r\n");\r
+ printf("Hello world!<br>\r\n");\r
+ printf("Request number %d.", count++);\r
+ }\r
+ exit(0);\r
+ }\r
+</PRE>\r
+ <P>\r
+ This application returns a "Hello world" HTML response to the client. It also keeps a counter of the\r
+ number of times it has been accessed, displaying the value of the counter at each request.\r
+ </P>\r
+ <P>\r
+ The <TT>fcgi_stdio.h</TT> header file provides the FastCGI replacement routines for the C standard I/O\r
+ library. The <TT>FCGI_Accept()</TT> routine accepts a new request from the Web server.\r
+ </P>\r
+ <H3>\r
+ Migrating Existing CGI Programs\r
+ </H3>\r
+ <P>\r
+ The application library was designed to make migration of existing CGI programs as simple as possible. Many\r
+ applications can be converted by adding a loop around the main request processing code and recompiling with\r
+ the FastCGI application library. FastCGI applications have the following structure, with an initialization\r
+ section and a request processing loop:\r
+ </P>\r
+ <P>\r
+ <I>Initialize application;<BR>\r
+ </I> <TT>while(FCGI_Accept() >= 0) {</TT><BR>\r
+ <I>Process request</I>;<BR>\r
+ <TT>}</TT>\r
+ </P>\r
+ <P>\r
+ To ease migration to FastCGI, executables built with the application library can run as either CGI or FastCGI\r
+ programs, depending on how they are invoked. The library detects the execution environment and automatically\r
+ selects FastCGI or regular I/O routines, as appropriate.\r
+ </P>\r
+ <P>\r
+ After migration, developers can clean up their FastCGI applications for best performance:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ Fix any resource leaks. Many CGI programs do not attempt to manage memory or close files, because they\r
+ assume the world is going to be cleaned up when they exit. (If you don't want to clean up your program,\r
+ you can just have your process assume that it is leaking memory and exit after processing some fixed number\r
+ of requests.) Purify from Pure Software is one of a number of excellent tools for finding leaks and other\r
+ memory use problems.\r
+ </LI>\r
+ <LI>\r
+ Fix any problems with retained application state. The application must ensure that any state that it\r
+ creates in processing one request has no unintended effects on later requests.\r
+ </LI>\r
+ <LI>\r
+ Collapse functionality. A common practice with CGI applications is to implement many small programs, with\r
+ one function per program. CGI encourages this, because smaller programs load faster. With FastCGI, it's\r
+ better to have related functionality in a single executable, so there are fewer processes to manage and\r
+ applications can take advantage of sharing cached information across functions.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ Applications written in Perl, Tcl, and other scripting languages can be migrated by using a language\r
+ interpreter built with the application library. FastCGI-integrated Tcl and Perl interpreters for popular Unix\r
+ platforms are available from Open Market. The interpreters are backward-compatible: They can run standard Tcl\r
+ and Perl applications.\r
+ </P>\r
+ <H2>\r
+ 5. FastCGI in the Open Market WebServer\r
+ </H2>\r
+ <P>\r
+ This section describes the FastCGI support in the following Open Market server products:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ Open Market WebServer V2.0\r
+ </LI>\r
+ <LI>\r
+ Open Market Secure WebServer V2.0\r
+ </LI>\r
+ <LI>\r
+ Open Market Secure WebServer (Global) V2.0\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ For more information about FastCGI support, see the <I>Open Market WebServer Installation and Configuration\r
+ Guide</I>.\r
+ </P>\r
+ <H3>\r
+ Server Configuration\r
+ </H3>\r
+ <P>\r
+ FastCGI applications are configured with the server's configuration file. Configuration has two parts.\r
+ </P>\r
+ <P>\r
+ First, the server administrator defines an <I>application class</I>. For local applications, the application\r
+ class specifies the details of running the FastCGI application, such as:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ The pathname of the application executable.\r
+ </LI>\r
+ <LI>\r
+ Any arguments and environment variables to pass to the process at startup.\r
+ </LI>\r
+ <LI>\r
+ The number of processes to run.\r
+ </LI>\r
+ </UL>\r
+ <P>\r
+ For remote applications, the class configuration information includes the host and TCP port to connect to. The\r
+ Web server assumes that the FastCGI application has been started on the remote host. If a request comes in and\r
+ the server can't connect to the FastCGI TCP port, the server logs an error and returns an error page to\r
+ the client.\r
+ </P>\r
+ <P>\r
+ The second configuration step is mapping the application class to a role:\r
+ </P>\r
+ <UL>\r
+ <LI>\r
+ For responder roles, the administrator configures some part of the URL space to be handled by the FastCGI\r
+ application. For example, all URLs beginning with <SPAN CLASS="c4">/rollcall/</SPAN> might be handled by\r
+ the employee database application.\r
+ </LI>\r
+ <LI>\r
+ For filter roles, the administrator configures a file extension to be handled by a filter application. For\r
+ example, all files with the <SPAN CLASS="c4">.sql</SPAN> extension could be handled by a SQL query lookup\r
+ filter.\r
+ </LI>\r
+ <LI>\r
+ For authorizer roles, the administrator configures an authorizer application in the same manner as other\r
+ access methods (hostname, username/password, etc.) A request must pass <I>all</I> access control checks\r
+ (possibly including multiple FastCGI authorizers) before access is allowed.\r
+ </LI>\r
+ </UL>\r
+ <H3>\r
+ Basic FastCGI\r
+ </H3>\r
+ <P>\r
+ To simplify migration for existing CGI programs, the WebServer provides a simple way to install new FastCGI\r
+ programs without having to reconfigure the server. However, this approach doesn't offer all of the\r
+ performance benefits of FastCGI application classes.\r
+ </P>\r
+ <P>\r
+ The WebServer treats any file with the extension <SPAN CLASS="c4">.fcg</SPAN> as a FastCGI application. When a\r
+ request corresponds to such a file, the WebServer creates a new FastCGI process to handle the request, and\r
+ shuts down the process when the request is complete (just as in CGI). In this mode of operation performance is\r
+ comparable to CGI. Future versions of the WebServer will improve performance by automatically caching\r
+ processes and re-using them for subsequent requests.\r
+ </P>\r
+ <H3>\r
+ Session Affinity\r
+ </H3>\r
+ <P>\r
+ FastCGI programs can improve performance by caching information in the application process. For applications\r
+ that require frequent but expensive operations such as validating a username/password in an external database\r
+ for each request, this technique can significantly improve performance.\r
+ </P>\r
+ <P>\r
+ To improve the effectiveness of this technique, the WebServer implements <I>session affinity</I>. When session\r
+ affinity is enabled, the WebServer arranges for all requests in a user session to be handled by the same\r
+ FastCGI application process. What constitutes a "session" is configurable. The default configuration\r
+ uses the WebServer's built-in session tracking facility to identify user sessions. However, the server\r
+ administrator can use any part of the request information for the session affinity mapping: the URL path, the\r
+ client's hostname, the username, etc.\r
+ <!--Talk about applications that need to hold onto resources for the user (such as open connections to the database).-->\r
+ </P>\r
+ <H2>\r
+ 6. FastCGI Performance Analysis\r
+ </H2>\r
+ <P>\r
+ How fast is FastCGI? The answer depends on the application. This section contains some real FastCGI\r
+ performance measurements, as well as guidelines for estimating the FastCGI speedup.\r
+ </P>\r
+ <H3>\r
+ FastCGI vs CGI\r
+ </H3>\r
+ <P>\r
+ We measured the relative performance of CGI, FastCGI, and static files on the Open Market WebServer, using a\r
+ simple application that generates a fixed number of output bytes. The following table shows the measured\r
+ request processing time for different request types on a typical platform. The times are measured from the\r
+ client perspective and include client, server, and application processing time.\r
+ </P>\r
+ <TABLE BORDERCOLOR="#000000" BORDER="2">\r
+ <TR>\r
+ <TD WIDTH="72">\r
+ <DIV CLASS="c5">\r
+ Static file\r
+ </DIV>\r
+ </TD>\r
+ <TD WIDTH="180">\r
+ <DIV CLASS="c5">\r
+ 21ms + 0.19ms per Kbyte\r
+ </DIV>\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="72">\r
+ <DIV CLASS="c5">\r
+ FastCGI\r
+ </DIV>\r
+ </TD>\r
+ <TD WIDTH="180">\r
+ <DIV CLASS="c5">\r
+ 22ms + 0.28ms per Kbyte\r
+ </DIV>\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="72">\r
+ <DIV CLASS="c5">\r
+ CGI\r
+ </DIV>\r
+ </TD>\r
+ <TD WIDTH="180">\r
+ <DIV CLASS="c5">\r
+ 59ms + 0.37ms per Kbyte\r
+ </DIV>\r
+ </TD>\r
+ </TR>\r
+ </TABLE>\r
+ <P>\r
+ FastCGI performance is comparable to serving static files, and significantly better than CGI (clearly showing\r
+ the high overhead for process creation). Real applications have an additional time component: process\r
+ initialization, which should be added to overall request processing time.\r
+ </P>\r
+ <P>\r
+ Let's use this data to estimate the speedup from migrating a typical database CGI application to FastCGI.\r
+ Assume the application takes 50ms to initialize the database connection and generates 5K of output data.\r
+ Request performance can be computed as follows:\r
+ </P>\r
+ <TABLE>\r
+ <TR>\r
+ <TD WIDTH="108">\r
+ CGI\r
+ </TD>\r
+ <TD WIDTH="331">\r
+ 59ms + 50ms + (0.37ms)(5) = 111ms\r
+ </TD>\r
+ </TR>\r
+ <TR>\r
+ <TD WIDTH="108">\r
+ FastCGI\r
+ </TD>\r
+ <TD WIDTH="331">\r
+ 22ms + (0.28ms)(5) = 23ms\r
+ </TD>\r
+ </TR>\r
+ </TABLE>\r
+ <P>\r
+ In this example, FastCGI has a 5x performance advantage over CGI, mostly due to savings from not having to\r
+ create and initialize new processes for each request.<!--Need to talk about FastCGI vs proprietary APIs.-->\r
+ </P>\r
+ <H2>\r
+ 7. Conclusions\r
+ </H2>\r
+ <P>\r
+ Today's Web business applications need a platform that's fast, open, maintainable, straightforward,\r
+ stable, and secure. FastCGI's design meets these requirements, and provides for a logical extension from\r
+ proven and widely deployed CGI technology. This allows developers to take advantage of FastCGI's benefits\r
+ without losing their existing investment in CGI applications.<!--Need to talk about NT.-->\r
+ \r
+ <!--Need to give "more punch" to this conclusion: include info about uses for FastCGI (accessing legacy data in databases, access control, distributed applications, apps that have to run in multiple OS environments. -->\r
+ </P>\r
+ <H2>\r
+ 8. For More Information\r
+ </H2>\r
+ <P>\r
+ For more information about Open Market and our products, visit our Web site at:<SPAN CLASS=\r
+ "c4">http://www.openmarket.com/</SPAN>\r
+ </P>\r
+ <P>\r
+ For more information about the FastCGI protocol and the developer's kit, and the latest information about\r
+ FastCGI standardization and support in other Web servers, visit the FastCGI project page at:<SPAN CLASS=\r
+ "c4">http://www.openmarket.com/fastcgi/</SPAN>\r
+ </P>\r
+ </BODY>\r
+</HTML>\r
+\r
projects / catagits/fcgi2.git / commitdiff