-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
<HTML>\r
<HEAD>\r
<TITLE>\r
<A HREF="http://fastcgi.com"><IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"></A>\r
</DIV>\r
<BR CLEAR="all">\r
+ \r
<DIV CLASS="c1">\r
<H3>\r
Integrating FastCGI with Perl-5\r
<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->\r
<H5 CLASS="c2">\r
Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>\r
- Tel: 617-949-7000 URL: <A HREF="http://www.openmarket.com/">http://www.openmarket.com/</A><BR>\r
- $Id: fcgi-perl.htm,v 1.3 2001/11/27 01:03:47 robs Exp $<BR>\r
+ Tel: 617-949-7000 URL: <A HREF="http://www.openmarket.com/">http://www.openmarket.com/</A><BR>\r
+ $Id: fcgi-perl.htm,v 1.4 2001/11/27 18:38:06 robs Exp $<BR>\r
</H5>\r
<HR>\r
- <UL TYPE="square">\r
- <LI>\r
- <A HREF="#S1">1. Introduction</A>\r
- </LI>\r
- <LI>\r
- <A HREF="#S2">2. Perl with sfio and an FCGI module</A>\r
- </LI>\r
- <LI>\r
- <A HREF="#S3">3. Perl with fcgi_stdio and an FCGI module</A> \r
- <UL TYPE="square">\r
- <LI>\r
- <A HREF="#S3.1">3.1 Basic recipe</A>\r
- </LI>\r
- <LI>\r
- <A HREF="#S3.2">3.2 Semi-advanced recipe</A>\r
- </LI>\r
- <LI>\r
- <A HREF="#S3.3">3.3 Advanced recipe</A>\r
- </LI>\r
- </UL>\r
- </LI>\r
- <LI>\r
- <A HREF="#S4">4. Writing FastCGI applications in Perl</A>\r
- </LI>\r
- </UL>\r
- <H3>\r
- <A NAME="S1">1. Introduction</A>\r
- </H3>\r
<P>\r
Perl (Practical Extraction and Report Language) is a scripting language that is often used for CGI\r
- programming. Perl is freely available as a source kit.\r
+ programming. Perl is freely available.\r
</P>\r
<P>\r
- FastCGI has been integrated with Perl in two different ways:\r
+ FastCGI support is available for Perl via the FCGI.pm Perl module. FCGI.pm no longer requires SFIO or a\r
+ specially-built Perl. FCGI.pm is available via CPAN as well as in the perl directory of this kit.\r
+ </P>\r
+ <P>\r
+ Please see the FCGI.pm documentation for examples and details.\r
</P>\r
- <OL>\r
- <LI>\r
- By writing a module that plugs into any Perl interpreter that's been built with sfio, a stdio\r
- alternative from AT&T.\r
- </LI>\r
- <LI>\r
- By writing a module that plugs into any Perl interpreter that's been built with FastCGI's\r
- fcgi_stdio library layering over stdio. The first approach, implemented by Sven Verdoolaege\r
- (skimo@breughel.ufsia.ac.be), is probably the better of the two, since sfio is a generally useful addition\r
- to Perl. The second approach, implemented by engineers at Open Market, predates the availability of an\r
- sfio-integrated Perl and demonstrates that the fcgi_stdio library can be used with a substantial C\r
- application.\r
- <P>\r
- The two approaches are compatible at the Perl source code level; a Perl application developed using one\r
- approach can be run using the other. And both approaches result in a general-purpose Perl interpreter,\r
- not a Perl interpreter that's only usable for FastCGI applications.\r
- </P>\r
- <P>\r
- This memo documents both approaches and explains a small Perl FastCGI application.\r
- </P>\r
- <P>\r
- </P>\r
- <H3>\r
- <A NAME="S2">2. Perl with sfio and an FCGI module</A>\r
- </H3>\r
- As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional support for sfio (safe/fast\r
- string/file I/O), which is an alternative to stdio that AT&T distributes freely. An advantage of sfio\r
- over stdio is that sfio provides the ability to implement new stream classes that don't simply transfer\r
- sequential bytes to or from a file descriptor. This flexibility is exactly what FastCGI needs in order to\r
- implement the standard I/O streams in a manner that's transparent to applications.\r
- <P>\r
- Perl interpreters incorporating sfio are not widely available in binary form, so most likely you'll\r
- have to build your own. Your build should go smoothly if you follow the instructions below. The\r
- instructions assume:\r
- </P>\r
- <P>\r
- </P>\r
- <UL>\r
- <LI>\r
- You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02) or higher. That's the first\r
- Perl release to support sfio.<BR>\r
- <BR>\r
- </LI>\r
- </UL>\r
- <P>\r
- Follow these steps to build a Perl with sfio:\r
- </P>\r
- <P>\r
- </P>\r
- <OL>\r
- <LI>\r
- Obtain sfio source code from <A HREF=\r
- "ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</A>\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Unpack the tar file using <TT>tar xvf</TT> command. <EM>$sfio</EM> will be used as a shorthand for\r
- the directory in which sfio package is installed.\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Update your $PATH variable as specified in <TT>$sfio/README</TT> and run <TT>make</TT> command in the\r
- <TT>$sfio/src/lib/sfio</TT> subdirectory.\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Rename or delete the file <TT>$sfio/include/stdio.h</TT>, since it may interfere in the further build\r
- process.\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from <A HREF=\r
- "http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</A>\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Unpack the tar file using <TT>tar xvf</TT> command. <EM>$perl</EM> is used as a shorthand for the\r
- directory that is created.\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Configure, build, and install Perl as follows: \r
-<PRE>\r
-% cd $perl\r
-% ./Configure -Duseperlio -Dusesfio\r
-% make \r
-% make test\r
-% make install\r
-</PRE>\r
- <P>\r
- There are certain Configure questions that must be answered differently when building Perl with\r
- sfio:\r
- </P>\r
- <P>\r
- </P>\r
- <DL>\r
- <DT>\r
- <EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio. However these are\r
- experimental and may cause problems with some extension modules. Use stdio as with previous\r
- versions? [y]</EM>\r
- </DT>\r
- <DD>\r
- You should answer no.\r
- </DD>\r
- <DD>\r
- <P>\r
- </P>\r
- </DD>\r
- <DT>\r
- <EM>Any additional cc flags?</EM>\r
- </DT>\r
- <DD>\r
- You should use the following cc flags along with any defaults that Perl Configure supplied: \r
- <UL>\r
- <LI>\r
- <STRONG>-I<EM>$sfio</EM>/include</STRONG>\r
- </LI>\r
- </UL>\r
- </DD>\r
- <DD>\r
- <P>\r
- </P>\r
- </DD>\r
- <DT>\r
- <EM>Any additional ld flags (NOT including libraries):</EM>\r
- </DT>\r
- <DD>\r
- You should specify the following <TT>ld</TT> flags: \r
- <UL>\r
- <LI>\r
- <STRONG>-L<EM>$sfio</EM>/lib</STRONG>\r
- </LI>\r
- </UL>\r
- </DD>\r
- <DD>\r
- <P>\r
- </P>\r
- </DD>\r
- <DT>\r
- <EM>Additional Libraries:</EM>\r
- </DT>\r
- <DD>\r
- Check that <STRONG>-lsfio</STRONG> is one of the specified libraries. Press return key to\r
- continue.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- </DL>\r
- <B>NOTE</B>: If you did not install Perl as a root user, make sure to correctly set environment\r
- variable <TT>PERL5LIB</TT> to indicate the location of Perl libraries. For example, if you installed\r
- Perl binary into the <TT>$INSTALL</TT> subdirectory and you are running Solaris, the following will\r
- set your proper library path: \r
-<PRE>\r
-% setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02\r
-</PRE>\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Obtain Perl/Sfio module for FastCGI support from <A HREF=\r
- "ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</A>\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Unpack FCGI module using <TT>tar</TT> command. We use <TT>$sfiomod</TT> to denote the subdirectory\r
- that is created in the process.\r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- Build and install the module with the following commands: \r
-<PRE>\r
-% cd $sfiomod\r
-% $INSTALL/bin/perl Makefile.PL\r
-% make\r
-% make test\r
-% make install\r
-</PRE>\r
- </LI>\r
- </OL>\r
- <H3>\r
- <A NAME="S3">3. Perl with fcgi_stdio and an FCGI module</A>\r
- </H3>\r
- <H4>\r
- <A NAME="S3.1">3.1 Basic recipe</A>\r
- </H4>\r
- Here are the assumptions embedded in the following recipe: \r
- <UL>\r
- <LI>\r
- You are building Perl 5.0 Patch 2 (5.002) or higher, since all examples that are provided are based\r
- on that release. <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- You have gcc version 2.7 installed on your system, and use it in the build. gcc is convenient because\r
- it supports the <TT>-include</TT> command-line option that instructs the C preprocessor to include a\r
- specific file before processing any other include files. This allows you to include\r
- <TT>fcgi_stdio.h</TT> without modifying Perl source files. (The reason for specifying gcc version 2.7\r
- is that I have experienced bad behavior with an earlier version and the <TT>-include</TT> flag -- the\r
- C preprocessor died with SIGABRT.) <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI developers kit.\r
- </LI>\r
- </UL>\r
- <P>\r
- If those are valid assumptions, follow these steps:\r
- </P>\r
- <OL>\r
- <LI>\r
- Pull the Perl source kit from <A HREF=\r
- "http://www.metronet.com/perlinfo/src/latest.tar.gz">http://www.metronet.com/perlinfo/src/latest.tar.gz</A>\r
- \r
- <P>\r
- There are good sources of information on Perl at:\r
- </P>\r
- <UL>\r
- <LI>\r
- <A HREF="http://www.perl.com/">http://www.perl.com/</A>\r
- </LI>\r
- <LI>\r
- <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>\r
- </LI>\r
- </UL>\r
- <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- Unpack the tar file in the parent directory of the FastCGI kit directory, so that the perl directory\r
- is a sibling of <TT>fcgi-devel-kit</TT>. <EM>$perl</EM> is used as shorthand for the full path of the\r
- directory in which Perl is installed. <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- Copy the version specific and the common files from <TT>fcgi-devel-kit/perl-5</TT> into the Perl-5\r
- kit. \r
-<PRE>\r
-> cd $perl\r
-> mv perl.c perl.c.orig\r
-> mv proto.h proto.h.orig\r
-> mv Configure Configure.orig\r
-> cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .\r
-> cp -r ../fcgi-devel-kit/perl-5/common/* .\r
-</PRE>\r
- <P>\r
- The files you are copying contain the Perl-5 FCGI extension, some files modified from the\r
- distribution, and a script to simplify the configuration process.\r
- </P>\r
- </LI>\r
- <LI>\r
- Set environment variables. The Perl-5 FastCGI configuration process requires that the environment\r
- variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI development kit. \r
-<PRE>\r
-> setenv FCGIDIR <EM>$fcgi</EM>\r
-</PRE>\r
- If you do not want to use <TT>gcc</TT> to build Perl you can set the environment variable <TT>CC</TT>\r
- to the desired compiler. For example: \r
-<PRE>\r
-> setenv CC gcc2.7\r
-</PRE>\r
- By default Perl's installation prefix is /usr/local, so binaries get installed in /usr/local/bin,\r
- library files get installed into /usr/local/lib/perl, etc. If you want to specify a different\r
- installation prefix set the environment variable <TT>PERL_PREFIX</TT>. \r
-<PRE>\r
-> setenv PERL_PREFIX /usr/local/perl5-fcgi\r
-</PRE>\r
- </LI>\r
- <LI>\r
- Run fcgi-configure. \r
-<PRE>\r
-> ./fcgi-configure\r
-</PRE>\r
- <P>\r
- <TT>fcgi-configure</TT> is a wrapper around Perl's <TT>Configure</TT> script. It sets some\r
- variables according the the value of some environment variables, and runs Perl's\r
- <TT>Configure</TT> script in such a way that it does not prompt the user for any input. 90% of the\r
- time this should work without a problem. If for some reason this does not work for you, you'll\r
- have to follow the steps in the next section.\r
- </P>\r
- <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- Run make. \r
-<PRE>\r
-> make\r
-</PRE>\r
- </LI>\r
- <LI>\r
- Install the newly built Perl-5. \r
-<PRE>\r
-> make install\r
-</PRE>\r
- </LI>\r
- </OL>\r
- <P>\r
- </P>\r
- <H4>\r
- <A NAME="S3.2">3.2 Semi-advanced recipe</A>\r
- </H4>\r
- If you do not have experience configuring and building Perl, you should find someone who does. Perl can be\r
- pretty intimidating to configure since it asks you a large number of irrelevant-seeming questions that you\r
- won't know how to answer.<BR>\r
- <BR>\r
- <BR>\r
- <BR>\r
- <OL>\r
- <LI>\r
- Go into the top level directory of the Perl distribution and run <TT>Configure</TT>. \r
-<PRE>\r
-> cd $perl\r
-> ./Configure\r
-</PRE>\r
- </LI>\r
- <LI>\r
- There are some questions that you are going to have to answer differently when building FastCGI into\r
- Perl. These are described below: <BR>\r
- <BR>\r
- <DL>\r
- <DT>\r
- <EM>Use which C compiler?</EM>\r
- </DT>\r
- <DD>\r
- You should specify <TT>gcc</TT>.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>Any additional cc flags?</EM>\r
- </DT>\r
- <DD>\r
- You should use the following cc flags along with any defaults that Perl Configure supplied: \r
- <UL>\r
- <LI>\r
- <STRONG>-I<EM>$fcgi</EM>/include</STRONG>\r
- </LI>\r
- <LI>\r
- <STRONG>-include <EM>$fcgi</EM>/include/fcgi_stdio.h</STRONG>\r
- </LI>\r
- </UL>\r
- This assumes you are using GCC.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>Any additional ld flags (NOT including libraries):</EM>\r
- </DT>\r
- <DD>\r
- You should specify the following <TT>ld</TT> flags: \r
- <UL>\r
- <LI>\r
- <STRONG>-L<EM>$fcgi</EM>/libfcgi</STRONG>\r
- </LI>\r
- </UL>\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>Additional Libraries:</EM>\r
- </DT>\r
- <DD>\r
- add <STRONG>-lfcgi</STRONG> to the list of additional libraries. It should be added before -lc.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>What extensions do you wish to load dynamically?</EM>\r
- </DT>\r
- <DD>\r
- If you can support dynamic extensions, <TT>Configure</TT> will ask which of the supplied\r
- extensions should be loaded dynamically. Since we copied the FCGI extension into the Perl\r
- source directory it should be one of the ones in the default list. If you want FCGI to be\r
- dynamically loaded you should specify it here, otherwise leave it out.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>What extensions do you wish to load statically?</EM>\r
- </DT>\r
- <DD>\r
- If you do not support Dynamic extensions this is the only question about extensions you would\r
- get asked. You should specify FCGI here if you did not get asked about dynamic extensions (or\r
- did not specify FCGI as a dynamic extension).\r
- </DD>\r
- </DL>\r
- <BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- Copy in the new <TT>proto.h</TT>. \r
- <P>\r
- The file proto.h has some macros that conflict with the FastCGI macros. The version of\r
- <TT>proto.h</TT> supplied in the FastCGI kit includes these changes:\r
- </P>\r
- <BR>\r
- <BR>\r
- <UL>\r
- <LI>\r
- At the beginning of the file it adds the following lines: \r
-<PRE>\r
-#ifdef _FCGI_STDIO\r
-#undef printf\r
-#endif\r
-</PRE>\r
- </LI>\r
- <LI>\r
- At the bottom it adds: \r
-<PRE>\r
-#ifdef _FCGI_STDIO\r
-#define printf FCGI_printf\r
-#endif\r
-</PRE>\r
- </LI>\r
- </UL>\r
- </LI>\r
- <LI>\r
- Copy in the new <TT>perl.c</TT>. \r
- <P>\r
- Perl-5.002 has a bug in <TT>perl.c</TT> that has a great chance of getting exercised with FastCGI.\r
- A fix has been sumbitted to the Perl developers and hopefully it'll make it into perl-5.003.\r
- It was a one line fix, here is a diff for the curious:\r
- </P>\r
-<PRE>\r
-*** perl.c 1996/03/15 17:10:10 1.1\r
---- perl.c 1996/03/15 17:11:23\r
-***************\r
-*** 405,410 ****\r
---- 405,411 ----\r
- if (e_fp) {\r
- if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))\r
- croak("Can't write to temp file for -e: %s", Strerror(errno));\r
-+ e_fp = Nullfp;\r
- argc++,argv--;\r
- scriptname = e_tmpname;\r
- }\r
-</PRE>\r
- Pretty straightforward.<BR>\r
- <BR>\r
- </LI>\r
- <LI>\r
- Build and install Perl. \r
-<PRE>\r
-> make\r
-<EM>[...]</EM>\r
-> make install\r
-</PRE>\r
- <BR>\r
- <BR>\r
- <H4>\r
- <A NAME="S3.3">3.3 Advanced recipe</A>\r
- </H4>\r
- <P>\r
- If you already have a Perl-5 package that has been configured, and you do not really want to\r
- re-run Configure, you can take the following steps.\r
- </P>\r
- <P CLASS="c3">\r
- <STRONG>THIS IS NOT RECOMMENDED</STRONG>\r
- </P>\r
- <P>\r
- Edit config.sh with your favorite editor and modify the following lines:\r
- </P>\r
- <DL>\r
- <DT>\r
- <EM>cc</EM>\r
- </DT>\r
- <DD>\r
- Change to use gcc if you are not using it already.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>ccflags</EM> AND <EM>cppflags</EM>\r
- </DT>\r
- <DD>\r
- Add the following flags: \r
- <UL>\r
- <LI>\r
- <STRONG>-I<EM>$fcgi</EM>/include</STRONG>\r
- </LI>\r
- <LI>\r
- <STRONG>-include <EM>$fcgi</EM>/include/fcgi_stdio.h</STRONG>\r
- </LI>\r
- </UL>\r
- This assumes you are using GCC. See the above section on assumptions\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>extensions</EM> AND <EM>known_extensions</EM>\r
- </DT>\r
- <DD>\r
- Add FCGI to the list of extensions\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>ldflags</EM>\r
- </DT>\r
- <DD>\r
- Add -L $fcgi/libfcgi to the list.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>libs</EM>\r
- </DT>\r
- <DD>\r
- Add -lfcgi to the list of libraries, should be added before -lc.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>static_ext</EM> <STRONG>or</STRONG> <EM>dynamic_ext</EM>\r
- </DT>\r
- <DD>\r
- Add FCGI to the list of statically or dynamically loaded extensions.\r
- </DD>\r
- <DD>\r
- <BR>\r
- <BR>\r
- </DD>\r
- <DT>\r
- <EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM>\r
- </DT>\r
- <DD>\r
- <DL>\r
- <DT>\r
- Change all of these to undef.\r
- </DT>\r
- </DL>\r
- <P>\r
- One you have edited config.sh you should do a "make Makefile depend all". If\r
- you're paranoid like me you may want to do a "make clean" first.\r
- </P>\r
- <H3>\r
- <A NAME="S4">4. Writing FastCGI applications in Perl</A>\r
- </H3>\r
- <P>\r
- The Perl program <TT>examples/tiny-perl-fcgi</TT> performs the same function as the C\r
- program <TT>examples/tiny-fcgi</TT> that's used as an example in the <A HREF=\r
- "fcgi-devel-kit.htm#S3.1.1">FastCGI Developer's Kit</A>. Here's what the Perl\r
- version looks like:\r
- </P>\r
-<PRE>\r
-#!./perl\r
-use FCGI;\r
-$count = 0;\r
-while(FCGI::accept() >= 0) {\r
- print("Content-type: text/html\r\n\r\n",\r
- "<title>FastCGI Hello! (Perl)</title>\n",\r
- "<h1>FastCGI Hello! (Perl)</h1>\n",\r
- "Request number ", $++count,\r
- " running on host <i>$ENV('SERVER_NAME')</i>");\r
-}\r
-</PRE>\r
- If you've built Perl according to the recipe and you have a Web server set up to run\r
- FastCGI applications, load the FastCGI Developer's Kit Index Page in that server and run\r
- this Perl application now. \r
- <P>\r
- The script invokes Perl indirectly via the symbolic link <TT>examples/perl</TT>. It does\r
- this because HP-UX has a limit of 32 characters for the first line of a command-interpreter\r
- file such as <TT>examples/tiny-perl-fcgi</TT>. If you run on HP-UX you won't want to\r
- sprinkle symbolic links to perl everywhere, so you should choose a <TT>PERL_PREFIX</TT>\r
- shorter than <TT>/usr/local/perl5-fcgi</TT>.\r
- </P>\r
- <P>\r
- You need to be aware of the following bug. If the initial environment to a FastCGI Perl\r
- application is empty (contains no name-value pairs) then when the first call to\r
- <TT>FCGI::accept</TT> returns, the environment will <I>still</I> be empty, i.e.\r
- <TT>%ENV</TT> will contain no associations. All the variables associated with the first\r
- request are lost. There are two known workarounds:\r
- </P>\r
- <P>\r
- </P>\r
- <UL>\r
- <LI>\r
- In your Perl application, enumerate <TT>%ENV</TT> using <TT>each</TT> before entering the\r
- <TT>FCGI::accept</TT> loop. The program <TT>examples/tiny-perl-fcgi</TT> contains code\r
- for this. \r
- <P>\r
- </P>\r
- </LI>\r
- <LI>\r
- In configuring your application be sure to set at least one initial environment variable.\r
- You do this with the <TT>AppClass -initial-env</TT> directive to the Web server, or by\r
- running <TT>cgi-fcgi</TT> in a non-empty environment.\r
- </LI>\r
- </UL>\r
- <P>\r
- The Perl subroutine <TT>FCGI::accept</TT> treats the initial environment differently than\r
- the C function <TT>FCGI_Accept</TT>. The first call to the C function <TT>FCGI_Accept</TT>\r
- replaces the initial environment with the environment of the first request. The first call\r
- to the Perl subroutine <TT>FCGI::accept</TT> adds the variable bindings of the first request\r
- to the bindings present in the initial environment. So when the first call to\r
- <TT>FCGI::accept</TT> returns, bindings from the initial environment are still there\r
- (unless, due to naming conflicts, some of them have been overwritten by the first request).\r
- The next call to <TT>FCGI::accept</TT> removes the bindings made on the previous call before\r
- adding a new set for the request just accepted, again preserving the initial environment.\r
- </P>\r
- <P>\r
- The Perl <TT>FCGI</TT> module also includes subroutines <TT>FCGI::finish</TT>,\r
- <TT>FCGI::set_exit_status</TT>, and <TT>FCGI::start_filter_data</TT> that correspond to C\r
- functions in <TT>fcgi_stdio.h</TT>; see the manpages for full information.\r
- </P>\r
- <P>\r
- Converting a Perl CGI application to FastCGI is not fundamentally different from converting\r
- a C CGI application. You separate the portion of the application that performs one-time\r
- initialization from the portion that performs per-request processing. You put the\r
- per-request processing into a loop controlled by <TT>FCGI::accept</TT>.\r
- </P>\r
- <P>\r
- </P>\r
- </DD>\r
- </DL>\r
- </LI>\r
- </OL>\r
- </LI>\r
- </OL>\r
</BODY>\r
</HTML>\r
\r
projects / catagits/fcgi2.git / commitdiff