projects / catagits/fcgi2.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | history | HEAD
fix validation, organization, and links
[catagits/fcgi2.git] / doc / fcgi-perl.htm
CommitLineData
e88ae2ce 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
2<HTML>\r
3 <HEAD>\r
4 <TITLE>\r
5 Integrating FastCGI with Perl-5\r
6 </TITLE>\r
7<STYLE TYPE="text/css">\r
8 body {\r
9 background-color: #FFFFFF;\r
10 color: #000000;\r
11 }\r
12 :link { color: #cc0000 }\r
13 :visited { color: #555555 }\r
14 :active { color: #000011 }\r
15 p.c3 {text-align: center}\r
16 h5.c2 {text-align: center}\r
17 div.c1 {text-align: center}\r
18</STYLE>\r
19 </HEAD>\r
20 <BODY>\r
21 <DIV CLASS="c1">\r
22 <A HREF="http://fastcgi.com"><IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"></A>\r
23 </DIV>\r
24 <BR CLEAR="all">\r
25 <DIV CLASS="c1">\r
26 <H3>\r
27 Integrating FastCGI with Perl-5\r
28 </H3>\r
29 </DIV>\r
30 <!--Copyright (c) 1996 Open Market, Inc. -->\r
31 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->\r
32 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->\r
33 <H5 CLASS="c2">\r
34 Copyright &copy; 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>\r
35 Tel: 617-949-7000 URL: <A HREF="http://www.openmarket.com/">http://www.openmarket.com/</A><BR>\r
36 $Id: fcgi-perl.htm,v 1.3 2001/11/27 01:03:47 robs Exp $<BR>\r
37 </H5>\r
38 <HR>\r
39 <UL TYPE="square">\r
40 <LI>\r
41 <A HREF="#S1">1. Introduction</A>\r
42 </LI>\r
43 <LI>\r
44 <A HREF="#S2">2. Perl with sfio and an FCGI module</A>\r
45 </LI>\r
46 <LI>\r
47 <A HREF="#S3">3. Perl with fcgi_stdio and an FCGI module</A> \r
48 <UL TYPE="square">\r
49 <LI>\r
50 <A HREF="#S3.1">3.1 Basic recipe</A>\r
51 </LI>\r
52 <LI>\r
53 <A HREF="#S3.2">3.2 Semi-advanced recipe</A>\r
54 </LI>\r
55 <LI>\r
56 <A HREF="#S3.3">3.3 Advanced recipe</A>\r
57 </LI>\r
58 </UL>\r
59 </LI>\r
60 <LI>\r
61 <A HREF="#S4">4. Writing FastCGI applications in Perl</A>\r
62 </LI>\r
63 </UL>\r
64 <H3>\r
65 <A NAME="S1">1. Introduction</A>\r
66 </H3>\r
67 <P>\r
68 Perl (Practical Extraction and Report Language) is a scripting language that is often used for CGI\r
69 programming. Perl is freely available as a source kit.\r
70 </P>\r
71 <P>\r
72 FastCGI has been integrated with Perl in two different ways:\r
73 </P>\r
74 <OL>\r
75 <LI>\r
76 By writing a module that plugs into any Perl interpreter that&#39;s been built with sfio, a stdio\r
77 alternative from AT&amp;T.\r
78 </LI>\r
79 <LI>\r
80 By writing a module that plugs into any Perl interpreter that&#39;s been built with FastCGI&#39;s\r
81 fcgi_stdio library layering over stdio. The first approach, implemented by Sven Verdoolaege\r
82 (skimo@breughel.ufsia.ac.be), is probably the better of the two, since sfio is a generally useful addition\r
83 to Perl. The second approach, implemented by engineers at Open Market, predates the availability of an\r
84 sfio-integrated Perl and demonstrates that the fcgi_stdio library can be used with a substantial C\r
85 application.\r
86 <P>\r
87 The two approaches are compatible at the Perl source code level; a Perl application developed using one\r
88 approach can be run using the other. And both approaches result in a general-purpose Perl interpreter,\r
89 not a Perl interpreter that&#39;s only usable for FastCGI applications.\r
90 </P>\r
91 <P>\r
92 This memo documents both approaches and explains a small Perl FastCGI application.\r
93 </P>\r
94 <P>\r
95 </P>\r
96 <H3>\r
97 <A NAME="S2">2. Perl with sfio and an FCGI module</A>\r
98 </H3>\r
99 As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional support for sfio (safe/fast\r
100 string/file I/O), which is an alternative to stdio that AT&amp;T distributes freely. An advantage of sfio\r
101 over stdio is that sfio provides the ability to implement new stream classes that don&#39;t simply transfer\r
102 sequential bytes to or from a file descriptor. This flexibility is exactly what FastCGI needs in order to\r
103 implement the standard I/O streams in a manner that&#39;s transparent to applications.\r
104 <P>\r
105 Perl interpreters incorporating sfio are not widely available in binary form, so most likely you&#39;ll\r
106 have to build your own. Your build should go smoothly if you follow the instructions below. The\r
107 instructions assume:\r
108 </P>\r
109 <P>\r
110 </P>\r
111 <UL>\r
112 <LI>\r
113 You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02) or higher. That&#39;s the first\r
114 Perl release to support sfio.<BR>\r
115 <BR>\r
116 </LI>\r
117 </UL>\r
118 <P>\r
119 Follow these steps to build a Perl with sfio:\r
120 </P>\r
121 <P>\r
122 </P>\r
123 <OL>\r
124 <LI>\r
125 Obtain sfio source code from <A HREF=\r
126 "ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</A>\r
127 <P>\r
128 </P>\r
129 </LI>\r
130 <LI>\r
131 Unpack the tar file using <TT>tar xvf</TT> command. <EM>$sfio</EM> will be used as a shorthand for\r
132 the directory in which sfio package is installed.\r
133 <P>\r
134 </P>\r
135 </LI>\r
136 <LI>\r
137 Update your $PATH variable as specified in <TT>$sfio/README</TT> and run <TT>make</TT> command in the\r
138 <TT>$sfio/src/lib/sfio</TT> subdirectory.\r
139 <P>\r
140 </P>\r
141 </LI>\r
142 <LI>\r
143 Rename or delete the file <TT>$sfio/include/stdio.h</TT>, since it may interfere in the further build\r
144 process.\r
145 <P>\r
146 </P>\r
147 </LI>\r
148 <LI>\r
149 Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from <A HREF=\r
150 "http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</A>\r
151 <P>\r
152 </P>\r
153 </LI>\r
154 <LI>\r
155 Unpack the tar file using <TT>tar xvf</TT> command. <EM>$perl</EM> is used as a shorthand for the\r
156 directory that is created.\r
157 <P>\r
158 </P>\r
159 </LI>\r
160 <LI>\r
161 Configure, build, and install Perl as follows: \r
162<PRE>\r
163% cd $perl\r
164% ./Configure -Duseperlio -Dusesfio\r
165% make \r
166% make test\r
167% make install\r
168</PRE>\r
169 <P>\r
170 There are certain Configure questions that must be answered differently when building Perl with\r
171 sfio:\r
172 </P>\r
173 <P>\r
174 </P>\r
175 <DL>\r
176 <DT>\r
177 <EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio. However these are\r
178 experimental and may cause problems with some extension modules. Use stdio as with previous\r
179 versions? [y]</EM>\r
180 </DT>\r
181 <DD>\r
182 You should answer no.\r
183 </DD>\r
184 <DD>\r
185 <P>\r
186 </P>\r
187 </DD>\r
188 <DT>\r
189 <EM>Any additional cc flags?</EM>\r
190 </DT>\r
191 <DD>\r
192 You should use the following cc flags along with any defaults that Perl Configure supplied: \r
193 <UL>\r
194 <LI>\r
195 <STRONG>-I<EM>$sfio</EM>/include</STRONG>\r
196 </LI>\r
197 </UL>\r
198 </DD>\r
199 <DD>\r
200 <P>\r
201 </P>\r
202 </DD>\r
203 <DT>\r
204 <EM>Any additional ld flags (NOT including libraries):</EM>\r
205 </DT>\r
206 <DD>\r
207 You should specify the following <TT>ld</TT> flags: \r
208 <UL>\r
209 <LI>\r
210 <STRONG>-L<EM>$sfio</EM>/lib</STRONG>\r
211 </LI>\r
212 </UL>\r
213 </DD>\r
214 <DD>\r
215 <P>\r
216 </P>\r
217 </DD>\r
218 <DT>\r
219 <EM>Additional Libraries:</EM>\r
220 </DT>\r
221 <DD>\r
222 Check that <STRONG>-lsfio</STRONG> is one of the specified libraries. Press return key to\r
223 continue.\r
224 </DD>\r
225 <DD>\r
226 <BR>\r
227 <BR>\r
228 </DD>\r
229 </DL>\r
230 <B>NOTE</B>: If you did not install Perl as a root user, make sure to correctly set environment\r
231 variable <TT>PERL5LIB</TT> to indicate the location of Perl libraries. For example, if you installed\r
232 Perl binary into the <TT>$INSTALL</TT> subdirectory and you are running Solaris, the following will\r
233 set your proper library path: \r
234<PRE>\r
235% setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02\r
236</PRE>\r
237 <P>\r
238 </P>\r
239 </LI>\r
240 <LI>\r
241 Obtain Perl/Sfio module for FastCGI support from <A HREF=\r
242 "ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</A>\r
243 <P>\r
244 </P>\r
245 </LI>\r
246 <LI>\r
247 Unpack FCGI module using <TT>tar</TT> command. We use <TT>$sfiomod</TT> to denote the subdirectory\r
248 that is created in the process.\r
249 <P>\r
250 </P>\r
251 </LI>\r
252 <LI>\r
253 Build and install the module with the following commands: \r
254<PRE>\r
255% cd $sfiomod\r
256% $INSTALL/bin/perl Makefile.PL\r
257% make\r
258% make test\r
259% make install\r
260</PRE>\r
261 </LI>\r
262 </OL>\r
263 <H3>\r
264 <A NAME="S3">3. Perl with fcgi_stdio and an FCGI module</A>\r
265 </H3>\r
266 <H4>\r
267 <A NAME="S3.1">3.1 Basic recipe</A>\r
268 </H4>\r
269 Here are the assumptions embedded in the following recipe: \r
270 <UL>\r
271 <LI>\r
272 You are building Perl 5.0 Patch 2 (5.002) or higher, since all examples that are provided are based\r
273 on that release. <BR>\r
274 <BR>\r
275 </LI>\r
276 <LI>\r
277 You have gcc version 2.7 installed on your system, and use it in the build. gcc is convenient because\r
278 it supports the <TT>-include</TT> command-line option that instructs the C preprocessor to include a\r
279 specific file before processing any other include files. This allows you to include\r
280 <TT>fcgi_stdio.h</TT> without modifying Perl source files. (The reason for specifying gcc version 2.7\r
281 is that I have experienced bad behavior with an earlier version and the <TT>-include</TT> flag -- the\r
282 C preprocessor died with SIGABRT.) <BR>\r
283 <BR>\r
284 </LI>\r
285 <LI>\r
286 <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI developers kit.\r
287 </LI>\r
288 </UL>\r
289 <P>\r
290 If those are valid assumptions, follow these steps:\r
291 </P>\r
292 <OL>\r
293 <LI>\r
294 Pull the Perl source kit from <A HREF=\r
295 "http://www.metronet.com/perlinfo/src/latest.tar.gz">http://www.metronet.com/perlinfo/src/latest.tar.gz</A>\r
296 \r
297 <P>\r
298 There are good sources of information on Perl at:\r
299 </P>\r
300 <UL>\r
301 <LI>\r
302 <A HREF="http://www.perl.com/">http://www.perl.com/</A>\r
303 </LI>\r
304 <LI>\r
305 <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>\r
306 </LI>\r
307 </UL>\r
308 <BR>\r
309 <BR>\r
310 </LI>\r
311 <LI>\r
312 Unpack the tar file in the parent directory of the FastCGI kit directory, so that the perl directory\r
313 is a sibling of <TT>fcgi-devel-kit</TT>. <EM>$perl</EM> is used as shorthand for the full path of the\r
314 directory in which Perl is installed. <BR>\r
315 <BR>\r
316 </LI>\r
317 <LI>\r
318 Copy the version specific and the common files from <TT>fcgi-devel-kit/perl-5</TT> into the Perl-5\r
319 kit. \r
320<PRE>\r
321&gt; cd $perl\r
322&gt; mv perl.c perl.c.orig\r
323&gt; mv proto.h proto.h.orig\r
324&gt; mv Configure Configure.orig\r
325&gt; cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .\r
326&gt; cp -r ../fcgi-devel-kit/perl-5/common/* .\r
327</PRE>\r
328 <P>\r
329 The files you are copying contain the Perl-5 FCGI extension, some files modified from the\r
330 distribution, and a script to simplify the configuration process.\r
331 </P>\r
332 </LI>\r
333 <LI>\r
334 Set environment variables. The Perl-5 FastCGI configuration process requires that the environment\r
335 variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI development kit. \r
336<PRE>\r
337&gt; setenv FCGIDIR <EM>$fcgi</EM>\r
338</PRE>\r
339 If you do not want to use <TT>gcc</TT> to build Perl you can set the environment variable <TT>CC</TT>\r
340 to the desired compiler. For example: \r
341<PRE>\r
342&gt; setenv CC gcc2.7\r
343</PRE>\r
344 By default Perl&#39;s installation prefix is /usr/local, so binaries get installed in /usr/local/bin,\r
345 library files get installed into /usr/local/lib/perl, etc. If you want to specify a different\r
346 installation prefix set the environment variable <TT>PERL_PREFIX</TT>. \r
347<PRE>\r
348&gt; setenv PERL_PREFIX /usr/local/perl5-fcgi\r
349</PRE>\r
350 </LI>\r
351 <LI>\r
352 Run fcgi-configure. \r
353<PRE>\r
354&gt; ./fcgi-configure\r
355</PRE>\r
356 <P>\r
357 <TT>fcgi-configure</TT> is a wrapper around Perl&#39;s <TT>Configure</TT> script. It sets some\r
358 variables according the the value of some environment variables, and runs Perl&#39;s\r
359 <TT>Configure</TT> script in such a way that it does not prompt the user for any input. 90% of the\r
360 time this should work without a problem. If for some reason this does not work for you, you&#39;ll\r
361 have to follow the steps in the next section.\r
362 </P>\r
363 <BR>\r
364 <BR>\r
365 </LI>\r
366 <LI>\r
367 Run make. \r
368<PRE>\r
369&gt; make\r
370</PRE>\r
371 </LI>\r
372 <LI>\r
373 Install the newly built Perl-5. \r
374<PRE>\r
375&gt; make install\r
376</PRE>\r
377 </LI>\r
378 </OL>\r
379 <P>\r
380 </P>\r
381 <H4>\r
382 <A NAME="S3.2">3.2 Semi-advanced recipe</A>\r
383 </H4>\r
384 If you do not have experience configuring and building Perl, you should find someone who does. Perl can be\r
385 pretty intimidating to configure since it asks you a large number of irrelevant-seeming questions that you\r
386 won&#39;t know how to answer.<BR>\r
387 <BR>\r
388 <BR>\r
389 <BR>\r
390 <OL>\r
391 <LI>\r
392 Go into the top level directory of the Perl distribution and run <TT>Configure</TT>. \r
393<PRE>\r
394&gt; cd $perl\r
395&gt; ./Configure\r
396</PRE>\r
397 </LI>\r
398 <LI>\r
399 There are some questions that you are going to have to answer differently when building FastCGI into\r
400 Perl. These are described below: <BR>\r
401 <BR>\r
402 <DL>\r
403 <DT>\r
404 <EM>Use which C compiler?</EM>\r
405 </DT>\r
406 <DD>\r
407 You should specify <TT>gcc</TT>.\r
408 </DD>\r
409 <DD>\r
410 <BR>\r
411 <BR>\r
412 </DD>\r
413 <DT>\r
414 <EM>Any additional cc flags?</EM>\r
415 </DT>\r
416 <DD>\r
417 You should use the following cc flags along with any defaults that Perl Configure supplied: \r
418 <UL>\r
419 <LI>\r
420 <STRONG>-I<EM>$fcgi</EM>/include</STRONG>\r
421 </LI>\r
422 <LI>\r
423 <STRONG>-include <EM>$fcgi</EM>/include/fcgi_stdio.h</STRONG>\r
424 </LI>\r
425 </UL>\r
426 This assumes you are using GCC.\r
427 </DD>\r
428 <DD>\r
429 <BR>\r
430 <BR>\r
431 </DD>\r
432 <DT>\r
433 <EM>Any additional ld flags (NOT including libraries):</EM>\r
434 </DT>\r
435 <DD>\r
436 You should specify the following <TT>ld</TT> flags: \r
437 <UL>\r
438 <LI>\r
439 <STRONG>-L<EM>$fcgi</EM>/libfcgi</STRONG>\r
440 </LI>\r
441 </UL>\r
442 </DD>\r
443 <DD>\r
444 <BR>\r
445 <BR>\r
446 </DD>\r
447 <DT>\r
448 <EM>Additional Libraries:</EM>\r
449 </DT>\r
450 <DD>\r
451 add <STRONG>-lfcgi</STRONG> to the list of additional libraries. It should be added before -lc.\r
452 </DD>\r
453 <DD>\r
454 <BR>\r
455 <BR>\r
456 </DD>\r
457 <DT>\r
458 <EM>What extensions do you wish to load dynamically?</EM>\r
459 </DT>\r
460 <DD>\r
461 If you can support dynamic extensions, <TT>Configure</TT> will ask which of the supplied\r
462 extensions should be loaded dynamically. Since we copied the FCGI extension into the Perl\r
463 source directory it should be one of the ones in the default list. If you want FCGI to be\r
464 dynamically loaded you should specify it here, otherwise leave it out.\r
465 </DD>\r
466 <DD>\r
467 <BR>\r
468 <BR>\r
469 </DD>\r
470 <DT>\r
471 <EM>What extensions do you wish to load statically?</EM>\r
472 </DT>\r
473 <DD>\r
474 If you do not support Dynamic extensions this is the only question about extensions you would\r
475 get asked. You should specify FCGI here if you did not get asked about dynamic extensions (or\r
476 did not specify FCGI as a dynamic extension).\r
477 </DD>\r
478 </DL>\r
479 <BR>\r
480 <BR>\r
481 </LI>\r
482 <LI>\r
483 Copy in the new <TT>proto.h</TT>. \r
484 <P>\r
485 The file proto.h has some macros that conflict with the FastCGI macros. The version of\r
486 <TT>proto.h</TT> supplied in the FastCGI kit includes these changes:\r
487 </P>\r
488 <BR>\r
489 <BR>\r
490 <UL>\r
491 <LI>\r
492 At the beginning of the file it adds the following lines: \r
493<PRE>\r
494#ifdef _FCGI_STDIO\r
495#undef printf\r
496#endif\r
497</PRE>\r
498 </LI>\r
499 <LI>\r
500 At the bottom it adds: \r
501<PRE>\r
502#ifdef _FCGI_STDIO\r
503#define printf FCGI_printf\r
504#endif\r
505</PRE>\r
506 </LI>\r
507 </UL>\r
508 </LI>\r
509 <LI>\r
510 Copy in the new <TT>perl.c</TT>. \r
511 <P>\r
512 Perl-5.002 has a bug in <TT>perl.c</TT> that has a great chance of getting exercised with FastCGI.\r
513 A fix has been sumbitted to the Perl developers and hopefully it&#39;ll make it into perl-5.003.\r
514 It was a one line fix, here is a diff for the curious:\r
515 </P>\r
516<PRE>\r
517*** perl.c 1996/03/15 17:10:10 1.1\r
518--- perl.c 1996/03/15 17:11:23\r
519***************\r
520*** 405,410 ****\r
521--- 405,411 ----\r
522 if (e_fp) {\r
523 if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))\r
524 croak(&quot;Can&#39;t write to temp file for -e: %s&quot;, Strerror(errno));\r
525+ e_fp = Nullfp;\r
526 argc++,argv--;\r
527 scriptname = e_tmpname;\r
528 }\r
529</PRE>\r
530 Pretty straightforward.<BR>\r
531 <BR>\r
532 </LI>\r
533 <LI>\r
534 Build and install Perl. \r
535<PRE>\r
536&gt; make\r
537<EM>[...]</EM>\r
538&gt; make install\r
539</PRE>\r
540 <BR>\r
541 <BR>\r
542 <H4>\r
543 <A NAME="S3.3">3.3 Advanced recipe</A>\r
544 </H4>\r
545 <P>\r
546 If you already have a Perl-5 package that has been configured, and you do not really want to\r
547 re-run Configure, you can take the following steps.\r
548 </P>\r
549 <P CLASS="c3">\r
550 <STRONG>THIS IS NOT RECOMMENDED</STRONG>\r
551 </P>\r
552 <P>\r
553 Edit config.sh with your favorite editor and modify the following lines:\r
554 </P>\r
555 <DL>\r
556 <DT>\r
557 <EM>cc</EM>\r
558 </DT>\r
559 <DD>\r
560 Change to use gcc if you are not using it already.\r
561 </DD>\r
562 <DD>\r
563 <BR>\r
564 <BR>\r
565 </DD>\r
566 <DT>\r
567 <EM>ccflags</EM> AND <EM>cppflags</EM>\r
568 </DT>\r
569 <DD>\r
570 Add the following flags: \r
571 <UL>\r
572 <LI>\r
573 <STRONG>-I<EM>$fcgi</EM>/include</STRONG>\r
574 </LI>\r
575 <LI>\r
576 <STRONG>-include <EM>$fcgi</EM>/include/fcgi_stdio.h</STRONG>\r
577 </LI>\r
578 </UL>\r
579 This assumes you are using GCC. See the above section on assumptions\r
580 </DD>\r
581 <DD>\r
582 <BR>\r
583 <BR>\r
584 </DD>\r
585 <DT>\r
586 <EM>extensions</EM> AND <EM>known_extensions</EM>\r
587 </DT>\r
588 <DD>\r
589 Add FCGI to the list of extensions\r
590 </DD>\r
591 <DD>\r
592 <BR>\r
593 <BR>\r
594 </DD>\r
595 <DT>\r
596 <EM>ldflags</EM>\r
597 </DT>\r
598 <DD>\r
599 Add -L $fcgi/libfcgi to the list.\r
600 </DD>\r
601 <DD>\r
602 <BR>\r
603 <BR>\r
604 </DD>\r
605 <DT>\r
606 <EM>libs</EM>\r
607 </DT>\r
608 <DD>\r
609 Add -lfcgi to the list of libraries, should be added before -lc.\r
610 </DD>\r
611 <DD>\r
612 <BR>\r
613 <BR>\r
614 </DD>\r
615 <DT>\r
616 <EM>static_ext</EM> <STRONG>or</STRONG> <EM>dynamic_ext</EM>\r
617 </DT>\r
618 <DD>\r
619 Add FCGI to the list of statically or dynamically loaded extensions.\r
620 </DD>\r
621 <DD>\r
622 <BR>\r
623 <BR>\r
624 </DD>\r
625 <DT>\r
626 <EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM>\r
627 </DT>\r
628 <DD>\r
629 <DL>\r
630 <DT>\r
631 Change all of these to undef.\r
632 </DT>\r
633 </DL>\r
634 <P>\r
635 One you have edited config.sh you should do a &quot;make Makefile depend all&quot;. If\r
636 you&#39;re paranoid like me you may want to do a &quot;make clean&quot; first.\r
637 </P>\r
638 <H3>\r
639 <A NAME="S4">4. Writing FastCGI applications in Perl</A>\r
640 </H3>\r
641 <P>\r
642 The Perl program <TT>examples/tiny-perl-fcgi</TT> performs the same function as the C\r
643 program <TT>examples/tiny-fcgi</TT> that&#39;s used as an example in the <A HREF=\r
644 "fcgi-devel-kit.htm#S3.1.1">FastCGI Developer&#39;s Kit</A>. Here&#39;s what the Perl\r
645 version looks like:\r
646 </P>\r
647<PRE>\r
648#!./perl\r
649use FCGI;\r
650$count = 0;\r
651while(FCGI::accept() &gt;= 0) {\r
652 print(&quot;Content-type: text/html\r\n\r\n&quot;,\r
653 &quot;&lt;title&gt;FastCGI Hello! (Perl)&lt;/title&gt;\n&quot;,\r
654 &quot;&lt;h1&gt;FastCGI Hello! (Perl)&lt;/h1&gt;\n&quot;,\r
655 &quot;Request number &quot;, $++count,\r
656 &quot; running on host &lt;i&gt;$ENV(&#39;SERVER_NAME&#39;)&lt;/i&gt;&quot;);\r
657}\r
658</PRE>\r
659 If you&#39;ve built Perl according to the recipe and you have a Web server set up to run\r
660 FastCGI applications, load the FastCGI Developer&#39;s Kit Index Page in that server and run\r
661 this Perl application now. \r
662 <P>\r
663 The script invokes Perl indirectly via the symbolic link <TT>examples/perl</TT>. It does\r
664 this because HP-UX has a limit of 32 characters for the first line of a command-interpreter\r
665 file such as <TT>examples/tiny-perl-fcgi</TT>. If you run on HP-UX you won&#39;t want to\r
666 sprinkle symbolic links to perl everywhere, so you should choose a <TT>PERL_PREFIX</TT>\r
667 shorter than <TT>/usr/local/perl5-fcgi</TT>.\r
668 </P>\r
669 <P>\r
670 You need to be aware of the following bug. If the initial environment to a FastCGI Perl\r
671 application is empty (contains no name-value pairs) then when the first call to\r
672 <TT>FCGI::accept</TT> returns, the environment will <I>still</I> be empty, i.e.\r
673 <TT>%ENV</TT> will contain no associations. All the variables associated with the first\r
674 request are lost. There are two known workarounds:\r
675 </P>\r
676 <P>\r
677 </P>\r
678 <UL>\r
679 <LI>\r
680 In your Perl application, enumerate <TT>%ENV</TT> using <TT>each</TT> before entering the\r
681 <TT>FCGI::accept</TT> loop. The program <TT>examples/tiny-perl-fcgi</TT> contains code\r
682 for this. \r
683 <P>\r
684 </P>\r
685 </LI>\r
686 <LI>\r
687 In configuring your application be sure to set at least one initial environment variable.\r
688 You do this with the <TT>AppClass -initial-env</TT> directive to the Web server, or by\r
689 running <TT>cgi-fcgi</TT> in a non-empty environment.\r
690 </LI>\r
691 </UL>\r
692 <P>\r
693 The Perl subroutine <TT>FCGI::accept</TT> treats the initial environment differently than\r
694 the C function <TT>FCGI_Accept</TT>. The first call to the C function <TT>FCGI_Accept</TT>\r
695 replaces the initial environment with the environment of the first request. The first call\r
696 to the Perl subroutine <TT>FCGI::accept</TT> adds the variable bindings of the first request\r
697 to the bindings present in the initial environment. So when the first call to\r
698 <TT>FCGI::accept</TT> returns, bindings from the initial environment are still there\r
699 (unless, due to naming conflicts, some of them have been overwritten by the first request).\r
700 The next call to <TT>FCGI::accept</TT> removes the bindings made on the previous call before\r
701 adding a new set for the request just accepted, again preserving the initial environment.\r
702 </P>\r
703 <P>\r
704 The Perl <TT>FCGI</TT> module also includes subroutines <TT>FCGI::finish</TT>,\r
705 <TT>FCGI::set_exit_status</TT>, and <TT>FCGI::start_filter_data</TT> that correspond to C\r
706 functions in <TT>fcgi_stdio.h</TT>; see the manpages for full information.\r
707 </P>\r
708 <P>\r
709 Converting a Perl CGI application to FastCGI is not fundamentally different from converting\r
710 a C CGI application. You separate the portion of the application that performs one-time\r
711 initialization from the portion that performs per-request processing. You put the\r
712 per-request processing into a loop controlled by <TT>FCGI::accept</TT>.\r
713 </P>\r
714 <P>\r
715 </P>\r
716 </DD>\r
717 </DL>\r
718 </LI>\r
719 </OL>\r
720 </LI>\r
721 </OL>\r
722 </BODY>\r
723</HTML>\r
724\r
Unnamed repository; edit this file to name it for gitweb.