2 <head><title>Integrating FastCGI with Perl-5</title>
5 <body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011"
9 <a href="/fastcgi/words">
10 <img border=0 src="/kit/images/fcgi-hd.gif" alt="[[FastCGI]]"></a>
13 <h3><center>Integrating FastCGI with Perl-5</center></h3>
15 <!--Copyright (c) 1996 Open Market, Inc. -->
16 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
17 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
20 Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
22 Tel: 617-949-7000 URL:
23 <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
24 $Id: fcgi-perl.htm,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
29 <li><a HREF = "#S1">1. Introduction</a>
30 <li><a HREF = "#S2">2. Perl with sfio and an FCGI module</a>
31 <li><a HREF = "#S3">3. Perl with fcgi_stdio and an FCGI module</a>
33 <li><a HREF = "#S3.1">3.1 Basic recipe</a>
34 <li><a HREF = "#S3.2">3.2 Semi-advanced recipe</a>
35 <li><a HREF = "#S3.3">3.3 Advanced recipe</a>
37 <li><a HREF = "#S4">4. Writing FastCGI applications in Perl</a>
41 <H3><A NAME = "S1"> 1. Introduction</A></H3>
42 Perl (Practical Extraction and Report Language) is a scripting language that
43 is often used for CGI programming. Perl is freely available as a
46 FastCGI has been integrated with Perl in two different ways:
48 <li>By writing a module that plugs into any Perl interpreter that's
49 been built with sfio, a stdio alternative from AT&T.
50 <li>By writing a module that plugs into any Perl interpreter that's
51 been built with FastCGI's fcgi_stdio library
54 The first approach, implemented by Sven Verdoolaege
55 (skimo@breughel.ufsia.ac.be), is probably the better of the two,
56 since sfio is a generally useful addition to Perl.
57 The second approach, implemented by engineers at Open Market,
58 predates the availability of an sfio-integrated
59 Perl and demonstrates that the fcgi_stdio library
60 can be used with a substantial C application.<p>
63 are compatible at the Perl source code level; a Perl
64 application developed using
65 one approach can be run using the other. And both approaches
66 result in a general-purpose Perl interpreter, not a Perl interpreter
67 that's only usable for FastCGI applications.<p>
69 This memo documents both approaches and explains a small
70 Perl FastCGI application.<p>
73 <h3><a name ="S2"> 2. Perl with sfio and an FCGI module</a></h3>
75 As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional
76 support for sfio (safe/fast string/file I/O), which is an alternative
77 to stdio that AT&T distributes freely. An advantage of sfio over stdio
78 is that sfio provides the ability to implement
79 new stream classes that don't simply transfer sequential bytes to or from
80 a file descriptor. This flexibility is exactly what FastCGI needs in order
81 to implement the standard I/O streams in a manner that's
82 transparent to applications.<p>
84 Perl interpreters incorporating sfio are not widely available in
85 binary form, so most likely you'll have to build your own.
86 Your build should go smoothly if you follow the instructions
87 below. The instructions assume:<p>
90 <li>You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02)
91 or higher. That's the first Perl release to support sfio.<p>
95 Follow these steps to build a Perl with sfio:<p>
98 <li>Obtain sfio source code from
99 <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">
100 ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</a><p>
102 <li>Unpack the tar file using <tt>tar xvf</tt> command. <EM>$sfio</EM>
103 will be used as a shorthand for the directory in which sfio package
106 <li>Update your $PATH variable as specified in <tt>$sfio/README</tt> and
107 run <tt>make</tt> command in the <tt>$sfio/src/lib/sfio</tt> subdirectory.<p>
109 <li>Rename or delete the file <tt>$sfio/include/stdio.h</tt>, since it may
110 interfere in the further build process.<p>
112 <li>Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from
113 <a href="http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">
114 http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</a><p>
116 <li>Unpack the tar file using <tt>tar xvf</tt> command. <EM>$perl</EM> is
117 used as a shorthand for the directory that is created.<p>
119 <li>Configure, build, and install Perl as follows:
123 % ./Configure -Duseperlio -Dusesfio
129 There are certain Configure questions that must be answered
130 differently when building Perl with sfio:<p>
134 <DT><EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio.
135 However these are experimental and may cause problems with some
137 Use stdio as with previous versions? [y] </EM></DT>
139 You should answer no.
142 <DT><EM>Any additional cc flags?</EM></DT>
144 You should use the following cc flags along with any defaults that Perl
147 <LI> <strong>-I<em>$sfio</em>/include</strong>
151 <DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
153 You should specify the following <tt>ld</tt> flags:
155 <LI> <strong>-L<em>$sfio</em>/lib</strong>
159 <DT><EM>Additional Libraries:</EM></DT>
161 Check that <strong>-lsfio</strong> is one of the specified libraries. Press
162 return key to continue.
166 <b>NOTE</b>: If you did not install Perl as a root user, make sure to
167 correctly set environment variable <tt>PERL5LIB</tt> to indicate the location
168 of Perl libraries. For example, if you installed Perl binary into the
169 <tt>$INSTALL</tt> subdirectory and you are running Solaris, the following
170 will set your proper library path:
172 % setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02
177 <li>Obtain Perl/Sfio module for FastCGI support from
178 <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">
179 ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</a><p>
181 <li>Unpack FCGI module using <tt>tar</tt> command. We use <tt>$sfiomod</tt>
182 to denote the subdirectory that is created in the process.<p>
184 <li>Build and install the module with the following commands:
187 % $INSTALL/bin/perl Makefile.PL
195 <H3><a NAME = "S3">3. Perl with fcgi_stdio and an FCGI module</a></H3>
197 <H4><a NAME = "S3.1">3.1 Basic recipe</a></H4>
199 Here are the assumptions embedded in the following recipe:
202 <LI>You are building Perl 5.0 Patch 2 (5.002) or higher, since
203 all examples that are provided are based on that release.
206 <LI>You have gcc version 2.7 installed on your system, and use it in the
207 build. gcc is convenient because it supports the <tt>-include</tt>
208 command-line option that instructs the C preprocessor to include a specific
209 file before processing any other include files. This allows you to include
210 <tt>fcgi_stdio.h</tt> without modifying Perl source files. (The reason for
211 specifying gcc version 2.7 is that I have experienced bad behavior with an
212 earlier version and the <tt>-include</tt> flag -- the C preprocessor died
216 <LI> <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI
220 If those are valid assumptions, follow these steps:
222 <LI> Pull the Perl source kit from
223 <A HREF="http://www.metronet.com/perlinfo/src/latest.tar.gz">
224 http://www.metronet.com/perlinfo/src/latest.tar.gz</A>
226 There are good sources of information on Perl at:
228 <LI> <A HREF="http://www.perl.com/">http://www.perl.com/</A>
229 <LI> <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>
233 <LI> Unpack the tar file in the parent directory of the FastCGI kit
234 directory, so that the perl directory is a sibling of <tt>fcgi-devel-kit</tt>.
235 <EM>$perl</EM> is used as shorthand for the full path of the directory
236 in which Perl is installed.
238 <LI> Copy the version specific and the common files from
239 <tt>fcgi-devel-kit/perl-5</tt> into the Perl-5 kit.
242 > mv perl.c perl.c.orig
243 > mv proto.h proto.h.orig
244 > mv Configure Configure.orig
245 > cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .
246 > cp -r ../fcgi-devel-kit/perl-5/common/* .
249 The files you are copying contain the Perl-5 FCGI extension, some
250 files modified from the distribution, and a script to simplify the
251 configuration process.
253 <LI> Set environment variables.
254 The Perl-5 FastCGI configuration process requires that the environment
255 variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI
258 > setenv FCGIDIR <EM>$fcgi</EM>
260 If you do not want to use <tt>gcc</tt> to build Perl you can set the
261 environment variable <TT>CC</TT> to the desired compiler. For example:
265 By default Perl's installation prefix is /usr/local, so binaries get
266 installed in /usr/local/bin, library files get installed into
267 /usr/local/lib/perl, etc. If you want to specify a different installation
268 prefix set the environment variable <tt>PERL_PREFIX</tt>.
270 > setenv PERL_PREFIX /usr/local/perl5-fcgi
272 <LI> Run fcgi-configure.
277 <TT>fcgi-configure</TT> is a wrapper around Perl's <tt>Configure</tt> script.
278 It sets some variables according the the value of some environment variables,
279 and runs Perl's <tt>Configure</tt> script
280 in such a way that it does not prompt the
281 user for any input. 90% of the time this should work without a problem.
282 If for some reason this does not work for you, you'll have to
283 follow the steps in the next section.<p>
288 <LI> Install the newly built Perl-5.
295 <H4><a NAME = "S3.2">3.2 Semi-advanced recipe</a></H4>
297 If you do not have experience configuring and building Perl, you
298 should find someone who does. Perl can be pretty intimidating to configure
299 since it asks you a large number of irrelevant-seeming
300 questions that you won't know how to answer.<p>
303 <LI>Go into the top level directory of the Perl distribution and run
310 There are some questions that you are going to
311 have to answer differently when building FastCGI into Perl.
312 These are described below:
315 <DT><EM>Use which C compiler?</EM></DT>
317 You should specify <tt>gcc</tt>.
320 <DT><EM>Any additional cc flags?</EM></DT>
322 You should use the following cc flags along with any defaults that Perl
325 <LI> <strong>-I<em>$fcgi</em>/include</strong>
326 <LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
328 This assumes you are using GCC.
332 <DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
334 You should specify the following <tt>ld</tt> flags:
336 <LI> <strong>-L<em>$fcgi</em>/libfcgi</strong>
341 <DT><EM>Additional Libraries:</EM></DT>
343 add <strong>-lfcgi</strong> to the list of additional libraries.
344 It should be added before -lc.
348 <DT><EM>What extensions do you wish to load dynamically?</EM></DT>
350 If you can support dynamic extensions, <tt>Configure</tt>
351 will ask which of the
352 supplied extensions should be loaded dynamically. Since we copied the FCGI
353 extension into the Perl source directory it should be one of the ones in the
354 default list. If you want FCGI to be dynamically loaded you should specify
355 it here, otherwise leave it out.
359 <DT><EM>What extensions do you wish to load statically?</EM></DT>
361 If you do not support Dynamic extensions this is the only question about
362 extensions you would get asked. You should specify FCGI here if you did not
363 get asked about dynamic extensions (or did not specify FCGI as a dynamic
368 <LI> Copy in the new <tt>proto.h</tt>.
370 The file proto.h has some macros that conflict with the FastCGI macros.
371 The version of <tt>proto.h</tt> supplied in the FastCGI kit
372 includes these changes:<p>
374 <LI> At the beginning of the file it adds the following lines:
380 <LI> At the bottom it adds:
383 #define printf FCGI_printf
387 <LI> Copy in the new <tt>perl.c</tt>.
389 Perl-5.002 has a bug in <tt>perl.c</tt> that has a great
390 chance of getting exercised
391 with FastCGI. A fix has been sumbitted to the Perl developers and hopefully
392 it'll make it into perl-5.003. It was a one line fix, here is a diff for the
395 *** perl.c 1996/03/15 17:10:10 1.1
396 --- perl.c 1996/03/15 17:11:23
401 if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))
402 croak("Can't write to temp file for -e: %s", Strerror(errno));
405 scriptname = e_tmpname;
408 Pretty straightforward.<p>
409 <LI> Build and install Perl.
417 <H4><a NAME = "S3.3">3.3 Advanced recipe</a></H4>
420 If you already have a Perl-5 package that has been configured, and you do
421 not really want to re-run Configure, you can take the following steps.
423 <P ALIGN=CENTER><STRONG>THIS IS NOT RECOMMENDED</STRONG></P>
425 Edit config.sh with your favorite editor and modify the following lines:
429 Change to use gcc if you are not using it already.
433 <DT><EM>ccflags</EM> AND <EM>cppflags</EM></DT>
435 Add the following flags:
437 <LI> <strong>-I<em>$fcgi</em>/include</strong>
438 <LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
440 This assumes you are using GCC. See the above section on assumptions
444 <DT><EM>extensions</EM> AND <EM>known_extensions</EM></DT>
446 Add FCGI to the list of extensions
450 <DT><EM>ldflags</EM></DT>
452 Add -L $fcgi/libfcgi to the list.
456 <DT><EM>libs</EM></DT>
458 Add -lfcgi to the list of libraries, should be added before -lc.
461 <DT><EM>static_ext</EM><STRONG> or </STRONG><EM>dynamic_ext</EM></DT>
463 Add FCGI to the list of statically or dynamically loaded extensions.
466 <DT><EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM></DT>
468 Change all of these to undef.
471 One you have edited config.sh you should do a "make Makefile depend all".
472 If you're paranoid like me you may want to do a "make clean" first.
476 <H3><A NAME = "S4"> 4. Writing FastCGI applications in Perl</A></H3>
478 The Perl program <tt>examples/tiny-perl-fcgi</tt> performs the same function as
479 the C program <tt>examples/tiny-fcgi</tt> that's used as an example in the
480 <A HREF="fcgi-devel-kit.html#S3.1.1">FastCGI Developer's Kit document</A>.
481 Here's what the Perl version looks like:
487 while(FCGI::accept() >= 0) {
488 print("Content-type: text/html\r\n\r\n",
489 "<title>FastCGI Hello! (Perl)</title>\n",
490 "<h1>FastCGI Hello! (Perl)</h1>\n",
491 "Request number ", $++count,
492 " running on host <i>$ENV('SERVER_NAME')</i>");
496 If you've built Perl according to the recipe and you have a Web server set
497 up to run FastCGI applications, load the FastCGI Developer's Kit Index Page
498 in that server and run this Perl application now.<p>
500 The script invokes Perl indirectly via the symbolic link
501 <tt>examples/perl</tt>. It does this because HP-UX has a limit of 32
502 characters for the first line of a command-interpreter file such as
503 <tt>examples/tiny-perl-fcgi</tt>. If you run on HP-UX you won't want
504 to sprinkle symbolic links to perl everywhere, so you should
505 choose a <tt>PERL_PREFIX</tt> shorter than <tt>/usr/local/perl5-fcgi</tt>.<p>
507 You need to be aware of the following bug. If the
508 initial environment to a FastCGI Perl application is empty (contains
509 no name-value pairs) then when the first call to <tt>FCGI::accept</tt>
510 returns, the environment will <i>still</i> be empty,
511 i.e. <tt>%ENV</tt> will contain no associations. All the variables
512 associated with the first request are lost. There are two known
517 In your Perl application, enumerate <tt>%ENV</tt> using
518 <tt>each</tt> before entering the <tt>FCGI::accept</tt>
519 loop. The program <tt>examples/tiny-perl-fcgi</tt>
520 contains code for this.<p>
522 In configuring your application be sure to set at least one
523 initial environment variable. You do this with the
524 <tt>AppClass -initial-env</tt> directive to the Web server,
525 or by running <tt>cgi-fcgi</tt> in a non-empty environment.
528 The Perl subroutine <tt>FCGI::accept</tt> treats the initial
529 environment differently than the C function <tt>FCGI_Accept</tt>. The
531 C function <tt>FCGI_Accept</tt> replaces the initial environment with
532 the environment of the first request. The first call to the Perl subroutine
533 <tt>FCGI::accept</tt> adds the variable bindings of the first request
534 to the bindings present in the initial environment. So when the first
535 call to <tt>FCGI::accept</tt> returns, bindings from the initial
536 environment are still there (unless, due to naming conflicts, some of
537 them have been overwritten by the first request). The next call to
538 <tt>FCGI::accept</tt> removes the bindings made on the previous call
539 before adding a new set for the request just accepted, again preserving
540 the initial environment.<p>
542 The Perl <tt>FCGI</tt> module also includes
543 subroutines <tt>FCGI::finish</tt>, <tt>FCGI::set_exit_status</tt>,
544 and <tt>FCGI::start_filter_data</tt> that correspond to
545 C functions in <tt>fcgi_stdio.h</tt>; see the manpages for
548 Converting a Perl CGI application to FastCGI is not fundamentally
549 different from converting a C CGI application. You separate
550 the portion of the application that performs one-time
551 initialization from the portion that performs per-request
552 processing. You put the per-request processing into a loop
553 controlled by <tt>FCGI::accept</tt>.<p>