1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
\r
5 FastCGI Developer's Kit
\r
7 <STYLE TYPE="text/css">
\r
9 background-color: #FFFFFF;
\r
12 :link { color: #cc0000 }
\r
13 :visited { color: #555555 }
\r
14 :active { color: #000011 }
\r
15 h5.c3 {text-align: center}
\r
16 h3.c2 {text-align: center}
\r
17 p.c1 {text-align: center}
\r
22 <IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"><BR CLEAR="all">
\r
25 FastCGI Developer's Kit
\r
27 <!--Copyright (c) 1996 Open Market, Inc. -->
\r
28 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
\r
29 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
\r
32 Open Market, Inc.<BR>
\r
35 Document Version: 1.08<BR>
\r
39 Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>
\r
40 Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=
\r
41 "http://www.openmarket.com/">http://www.openmarket.com/</A><BR>
\r
42 $Id: fcgi-devel-kit.htm,v 1.4 2001/11/27 01:03:47 robs Exp $<BR>
\r
47 <A HREF="#S1">1. Introduction</A>
\r
50 <A HREF="#S2">2. Getting started</A>
\r
53 <A HREF="#S3">3. Writing applications</A>
\r
56 <A HREF="#S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>
\r
59 <A HREF="#S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>
\r
62 <A HREF="#S3.3">3.3 Using Perl and Tcl</A>
\r
65 <A HREF="#S3.4">3.4 Using Java</A>
\r
70 <A HREF="#S4">4. Running applications</A>
\r
73 <A HREF="#S4.1">4.1 Using a Web server that supports FastCGI</A>
\r
76 <A HREF="#S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>
\r
81 <A HREF="#S5">5. Known problems</A>
\r
84 <A HREF="#S6">6. Getting support</A>
\r
89 <A NAME="S1">1. Introduction</A>
\r
92 FastCGI is an open extension to CGI that provides high performance for all Internet applications without the
\r
93 penalties of Web server APIs.
\r
96 FastCGI is designed to be layered on top of existing Web server APIs. For instance, the <TT>mod_fastcgi</TT>
\r
97 Apache module adds FastCGI support to the Apache server. FastCGI can also be used, with reduced functionality
\r
98 and reduced performance, on any Web server that supports CGI.
\r
101 This FastCGI Developer's Kit is designed to make developing FastCGI applications easy. The kit currently
\r
102 supports FastCGI applications written in C/C++, Perl, Tcl, and Java.
\r
109 Describes how to configure and build the kit for your development platform.
\r
112 Tells how to write applications using the libraries in the kit.
\r
115 Tells how to run applications using Web servers that support FastCGI or using any Web server and
\r
120 The kit includes a <A HREF="fastcgi-whitepaper/fastcgi.htm">technical white paper</A>,
\r
121 <TT>doc/fastcgi-whitepaper/fastcgi.htm</TT>. You should read at least the first three sections of the
\r
122 technical white paper before starting to write FastCGI applications. The <A HREF="fcgi-perf.htm">performance
\r
123 paper</A> will help you understand how application design affects performance with FastCGI.
\r
126 The <A HREF="fcgi-spec.html">FastCGI Specification</A>, <TT>doc/fcgi-spec.html</TT>, defines the interface
\r
127 between a FastCGI application and a Web server that supports FastCGI. The software in the kit implements the
\r
128 specification. You don't need to read the specification in order to write applications.
\r
131 Additional information is provided in the <A HREF="http://fastcgi.com/docs/faq.html">FAQ</A> document, which
\r
132 contains frequently asked questions about application development using FastCGI, as well as some general
\r
136 Experience with CGI programming will be extremely valuable in writing FastCGI applications. If you don't
\r
137 have enough experience with CGI programming, you should read one of the popular books on the topic or study
\r
138 the <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</A>. For a more formal treatment of CGI/1.1 see
\r
139 the <A HREF="http://cgi-spec.golux.com/">Internet Draft CGI 1.1 Specification</A>.
\r
142 <A NAME="S2">2. Getting started</A>
\r
145 The kit is a compressed tar (tar.Z) file, distributed via the <A HREF="http://fastcgi.com/">fastcgi.com</A>
\r
146 Web page. Unpacking the tar file creates a new directory <TT>fcgi-devel-kit</TT>.
\r
149 Open the kit's index page, <TT>fcgi-devel-kit/index.html</TT>, using the "Open File" command in
\r
150 your Web browser. The index page gives you an overview of the kit structure and helps you navigate the kit.
\r
151 The index page also contains links that run some example applications, but the applications won't work
\r
152 when index.html is opened using the "Open File" command because they aren't aren't being
\r
153 accessed through a Web server.
\r
156 In order to use the kit in earnest you'll need a Web server that you control, a Web server running with
\r
157 your user ID. The Web server will be starting FastCGI applications that you will need to debug; this will be a
\r
158 lot more convenient for you if these processes run with your user ID. It is best to have a Web server that
\r
159 supports FastCGI. <A HREF="#S4">Section 4</A> discusses Web server issues.
\r
162 If you can, keep the kit on a file system accessible from your personal workstation, do your builds on your
\r
163 workstation, and run your Web server on your workstation. If that's not possible, arrange a configuration
\r
164 such that the kit is accessible from the machine that's going to run your Web server, and build the kit
\r
165 and your applications on a machine that's configured exactly the same way (same processor architecture,
\r
166 operating system, etc.) as the machine that's going to run your Web server.
\r
169 To build the kit you execute this sequence of commands in the <TT>fcgi-devel-kit</TT> directory:
\r
176 We've built and exercised the kit on these platforms (listed in alphabetical order):
\r
180 BSD/OS 1.1 (Intel Pentium), gcc
\r
183 Digital UNIX V3.2 148 (Alpha), gcc/cc
\r
186 Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc
\r
189 IBM AIX 1 4 (RS/6000), gcc
\r
192 Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc
\r
195 Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc
\r
198 Sun SunOS 4.1.4 (SPARC), gcc
\r
202 Once you've built the kit, follow the directions in <A HREF="#S4">Section 4</A> to bring up your Web
\r
203 server and run the example applications.
\r
206 <A NAME="S3">3. Writing applications</A>
\r
209 <A NAME="S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>
\r
212 The <TT>fcgi_stdio</TT> library provides the easiest transition for C CGI programs and C CGI programmers to
\r
213 FastCGI. Using this library your application can run using either CGI or FastCGI, with the same binary for
\r
217 To introduce the <TT>fcgi_stdio</TT> library we give a pair of examples: a tiny CGI program and the
\r
218 translation of this program to FastCGI. These two example programs are included in the kit.
\r
221 The CGI program is <TT>examples/tiny-cgi.c</TT>:
\r
224 #include <stdio.h>
\r
225 #include <stdlib.h>
\r
230 printf("Content-type: text/html\r\n"
\r
232 "<title>CGI Hello!</title>"
\r
233 "<h1>CGI Hello!</h1>"
\r
234 "Request number %d running on host <i>%s</i>\n",
\r
235 ++count, getenv("SERVER_NAME"));
\r
239 The key features of this tiny CGI program are:
\r
243 The program sends data to the Web server by writing to <TT>stdout</TT>, using <TT>printf</TT> in this
\r
244 example. The CGI program first sends a <TT>Content-type</TT> header, then a small HTML document. The
\r
245 program includes <TT>stdio.h</TT> in order to get access to the <TT>printf</TT> function.
\r
248 The program obtains parameters provided by the Web server by reading environment variables. The CGI program
\r
249 reads the <TT>SERVER_NAME</TT> variable using <TT>getenv</TT> and includes the value in the HTML document.
\r
250 The program includes <TT>stdlib.h</TT> in order to get access to the <TT>getenv</TT> function.
\r
254 The <TT>count</TT> variable is degenerate in this example; the CGI program runs a single request, so the
\r
255 request number is always one. This variable will be more interesting in the FastCGI example.
\r
258 <A NAME="S3.1.1">The</A> corresponding FastCGI program is <TT>examples/tiny-fcgi.c</TT>:
\r
261 #include "fcgi_stdio.h"
\r
262 #include <stdlib.h>
\r
267 while(FCGI_Accept() >= 0)
\r
268 printf("Content-type: text/html\r\n"
\r
270 "<title>FastCGI Hello!</title>"
\r
271 "<h1>FastCGI Hello!</h1>"
\r
272 "Request number %d running on host <i>%s</i>\n",
\r
273 ++count, getenv("SERVER_NAME"));
\r
277 The key features of this tiny FastCGI program are:
\r
281 The program is structured as a loop that begins by calling the function <TT>FCGI_Accept</TT>. The
\r
282 <TT>FCGI_Accept</TT> function blocks until a new request arrives for the program to execute. The program
\r
283 includes <TT>fcgi_stdio.h</TT> in order to get access to the <TT>FCGI_Accept</TT> function.
\r
286 Within the loop, <TT>FCGI_Accept</TT> creates a CGI-compatible world. <TT>printf</TT> and <TT>getenv</TT>
\r
287 operate just as in the CGI program. <TT>stdin</TT> and <TT>stderr</TT>, not used by this tiny program, also
\r
288 operate just as in a CGI program.
\r
292 The <TT>count</TT> variable increments each time through the loop, so the program displays a new request
\r
293 number each time. You can use the reload button in your browser to demonstrate this, once you've got the
\r
294 program built and running.
\r
297 Building the program
\r
300 If you can build <TT>examples/tiny-cgi.c</TT>, it will be straightforward for you to build
\r
301 <TT>examples/tiny-fcgi.c</TT>. You need to:
\r
305 Add the directory containing the <TT>fcgi_stdio.h</TT> header to the compiler's include search path.
\r
306 The kit calls this directory <TT>include</TT>.
\r
309 Add the library <TT>libfcgi.a</TT> to the linker's command line so that it will be searched when
\r
310 linking. The <TT>libfcgi.a</TT> library implements the functions defined in <TT>fcgi_stdio.h</TT>. The kit
\r
311 calls the directory containing this library <TT>libfcgi</TT>.
\r
314 Determine whether or not the linker on your platform searches the Berkeley socket library by default, and
\r
315 if not, add linker directives to force this search.
\r
319 See <TT>examples/Makefile</TT> (created by <TT>configure</TT>) for a Makefile that builds both programs.
\r
320 Autoconf handles the platform-dependent linking issues; to see how, examine <TT>configure.in</TT> and
\r
321 <TT>examples/Makefile.in</TT>.
\r
324 Running the program
\r
327 <A HREF="#S4">Section 4</A> is all about how to run FastCGI applications.
\r
330 You can use CGI to run application binaries built with the <TT>fcgi_stdio</TT> library. The
\r
331 <TT>FCGI_Accept</TT> function tests its environment to determine how the application was invoked. If it was
\r
332 invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns
\r
333 <TT>-1</TT>. In effect, the request loop disappears.
\r
336 Of course, when a FastCGI application is run using CGI it does not get the benefits of FastCGI. For instance,
\r
337 the application exits after servicing a single request, so it cannot maintain cached information.
\r
340 Implementation details
\r
343 <TT>fcgi_stdio.h</TT> works by first including <TT>stdio.h</TT>, then defining macros to replace essentially
\r
344 all of the types and procedures defined in <TT>stdio.h</TT>. (<TT>stdio.h</TT> defines a few procedures that
\r
345 have nothing to do with <TT>FILE *</TT>, such as <TT>sprintf</TT> and <TT>sscanf</TT>; <TT>fcgi_stdio.h</TT>
\r
346 doesn't replace these.) For instance, <TT>FILE</TT> becomes <TT>FCGI_FILE</TT> and <TT>printf</TT> becomes
\r
347 <TT>FCGI_printf</TT>. You'll only see these new names if you read <TT>fcgi_stdio.h</TT> or examine your C
\r
348 source code after preprocessing.
\r
351 Here are some consequences of this implementation technique:
\r
355 On some platforms the implementation will break if you include <TT>stdio.h</TT> after including
\r
356 <TT>fcgi_stdio.h</TT>, because <TT>stdio.h</TT> often defines macros for functions such as <TT>getc</TT>
\r
357 and <TT>putc</TT>. Fortunately, on most platforms <TT>stdio.h</TT> is protected against multiple includes
\r
358 by lines near the top of the file that look like
\r
365 The specific symbol used for multiple-include protection, <TT>_STDIO_H</TT> in this example, varies from
\r
366 platform to platform. As long as your platform protects <TT>stdio.h</TT> against multiple includes, you
\r
367 can forget about this issue.
\r
371 If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you have source
\r
372 code, then you'll want to recompile these libraries with <TT>fcgi_stdio.h</TT> included. Most C
\r
373 compilers provide a command-line option for including headers in a program being compiled; using such a
\r
374 compiler feature allows you to rebuild your libraries without making source changes. For instance the gcc
\r
377 gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c
\r
381 causes gcc to include <TT>fcgi_stdio.h</TT> before it even begins to read the module
\r
382 <TT>wonderlib.c</TT>.
\r
386 If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you do not have
\r
387 source code, then you'll need to include the headers for these libraries <I>before</I> you include
\r
388 <TT>fcgi_stdio.h</TT>. You can't pass the <TT>stdin</TT>, <TT>stdout</TT>, or <TT>stderr</TT> streams
\r
389 produced by <TT>FCGI_Accept</TT> to any functions implemented by these libraries. You can pass a stream on
\r
390 a Unix file to a library function by following this pattern:
\r
392 FILE *myStream = fopen(path, "r");
\r
393 answer = MungeStream(FCGI_ToFile(myStream));
\r
397 Here <TT>MungeStream</TT> is a library function that you can't recompile and <TT>FCGI_ToFile</TT> is
\r
398 a macro that converts from <TT>FCGI_FILE *</TT> to <TT>FILE *</TT>. The macro <TT>FCGI_ToFile</TT> is
\r
399 defined in <TT>fcgi_stdio.h</TT>.
\r
404 Converting CGI programs
\r
407 The main task in converting a CGI program into a FastCGI program is separating the code that needs to execute
\r
408 once, initializing the program, from the code that needs to run for each request. In our tiny example,
\r
409 initializing the <TT>count</TT> variable is outside the loop, while incrementing the <TT>count</TT> variable
\r
413 Retained application state may be an issue. You must ensure that any application state created in processing
\r
414 one request has no unintended effects on later requests. FastCGI offers the possibility of significant
\r
415 application performance improvements, through caching; it is up to you to make the caches work correctly.
\r
418 Storage leaks may be an issue. Many CGI programs don't worry about storage leaks because the programs
\r
419 don't run for long enough for bloating to be a problem. When converting to FastCGI, you can either use a
\r
420 tool such as <A HREF="http://www.pure.com/"><I>Purify</I></A> from Pure Software to discover and fix storage
\r
421 leaks, or you can run a C garbage collector such as <A HREF="http://www.geodesic.com/"><I>Great Circle</I></A>
\r
422 from Geodesic Systems.
\r
428 Currently there are some limits to the compatibility provided by the <TT>fcgi_stdio</TT> library:
\r
432 The library does not provide FastCGI versions of the functions <TT>fscanf</TT> and <TT>scanf</TT>. If you
\r
433 wish to apply <TT>fscanf</TT> or <TT>scanf</TT> to <TT>stdin</TT> of a FastCGI program, the workaround is
\r
434 to read lines or other natural units into memory and then call <TT>sscanf</TT>. If you wish to apply
\r
435 <TT>fscanf</TT> to a stream on a Unix file, the workaround is to follow the pattern:
\r
437 FILE *myStream = fopen(path, "r");
\r
438 count = fscanf(FCGI_ToFile(myStream), format, ...);
\r
444 Reference documentation
\r
447 The <A HREF="FCGI_Accept.3"><TT>FCGI_Accept</TT> manpage</A>, <TT>doc/FCGI_Accept.3</TT>, describes the
\r
448 function in the traditional format.
\r
451 The <A HREF="FCGI_Finish.3"><TT>FCGI_Finish</TT></A> (<TT>doc/FCGI_Finish.3</TT>), <A HREF=
\r
452 "FCGI_SetExitStatus.3"><TT>FCGI_SetExitStatus</TT></A> (<TT>doc/FCGI_SetExitStatus.3</TT>), and <A HREF=
\r
453 "FCGI_StartFilterData.3"><TT>FCGI_StartFilterData</TT></A> (<TT>doc/FCGI_StartFilterData.3</TT>) manpages
\r
454 document capabilities of the <TT>fcgi-stdio</TT> library that are not illustrated above.
\r
457 <A NAME="S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>
\r
460 The <TT>fcgiapp</TT> library is a second C library for FastCGI. It does not provide the high degree of source
\r
461 code compatibility provided by <TT>fcgi_stdio</TT>; in return, it does not make such heavy use of
\r
462 <TT>#define</TT>. <TT>fcgi_stdio</TT> is implemented as a thin layer on top of <TT>fcgiapp</TT>.
\r
465 Applications built using the <TT>fcgiapp</TT> library cannot run as CGI programs; that feature is provided at
\r
466 the <TT>fcgi_stdio</TT> level.
\r
469 Functions defined in <TT>fcgiapp</TT> are named using the prefix <TT>FCGX_</TT> rather than <TT>FCGI_</TT>.
\r
470 For instance, <TT>FCGX_Accept</TT> is the <TT>fcgiapp</TT> version of <TT>FCGI_Accept</TT>.
\r
473 Documentation of the <TT>fcgiapp</TT> library takes the form of extensive comments in the header file
\r
474 <TT>include/fcgiapp.h</TT>. The sample programs <TT>examples/tiny-fcgi2.c</TT> and <TT>examples/echo2.c</TT>
\r
475 illustrate how to use <TT>fcgiapp</TT>.
\r
478 <A NAME="S3.3">3.3 Using Perl and Tcl</A>
\r
481 A major advantage of the FastCGI approach to high-performance Web applications is its language-neutrality. CGI
\r
482 scripts written in popular languages such as Perl and Tcl can be evolved into high-performance FastCGI
\r
486 We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since Perl and Tcl are
\r
487 conventional C applications and <TT>fcgi_stdio</TT> was designed for converting conventional C applications.
\r
488 Essentially no source code changes were required in these programs; a small amount of code was added in order
\r
489 to make <TT>FCGI_Accept</TT> and other FastCGI primitives available in these languages. And because these
\r
490 interpreters were developed using <TT>fcgi_stdio</TT>, they run standard Perl and Tcl applications (e.g. CGI
\r
491 scripts) as well as FastCGI applications.
\r
494 See the <A HREF="http://fastcgi.com">fastcgi.com</A> Web page for more information about the Perl and Tcl
\r
498 Here are the Perl and Tcl versions of <TT>tiny-fcgi</TT>:
\r
504 while(FCGI::accept() >= 0) {
\r
505 print("Content-type: text/html\r\n\r\n",
\r
506 "<title>FastCGI Hello! (Perl)</title>\n",
\r
507 "<h1>FastCGI Hello! (Perl)</h1>\n";
\r
508 "Request number ", ++$count,
\r
509 " running on host <i>";$env(SERVER_NAME)</i>");
\r
515 while {[FCGI_Accept] >= 0 } {
\r
517 puts -nonewline "Content-type: text/html\r\n\r\n"
\r
518 puts "<title>FastCGI Hello! (Tcl)</title>"
\r
519 puts "<h1>FastCGI Hello! (Tcl)</h1>"
\r
520 puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
\r
524 Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI
\r
525 application to FastCGI. You separate the portion of the application that performs one-time initialization from
\r
526 the portion that performs per-request processing. You put the per-request processing into a loop controlled by
\r
527 <TT>FCGI::accept</TT> (Perl) or <TT>FCGI_Accept</TT> (Tcl).
\r
530 <A NAME="S3.4">3.4 Using Java</A>
\r
533 Java is not just for browser-based applets. It is already suitable for writing some Web server applications,
\r
534 and its range of applicability will only grow as Java compilers and other Java tools improve. Java's
\r
535 modules, garbage collection, and threads are especially valuable for writing long-lived application servers.
\r
538 The <TT>FCGIInterface</TT> class provides facilities for Java applications analogous to what
\r
539 <TT>fcgi_stdio</TT> provides for C applications. Using this library your Java application can run using either
\r
543 The kit includes separate companion document on <A HREF="fcgi-java.htm">using FastCGI with Java</A>. The
\r
544 source code for FastCGI classes is contained in directory <TT>java/src</TT> and the compiled code in
\r
545 <TT>java/classes</TT>.
\r
548 Here is the Java version of <TT>tiny-fcgi</TT>:
\r
551 import FCGIInterface;
\r
554 public static void main (String args[]) {
\r
556 while(new FCGIInterface().FCGIaccept()>= 0) {
\r
558 System.out.println("Content-type: text/html\r\n\r\n");
\r
559 System.out.println(
\r
560 "<title>FastCGI Hello! (Java)</title>");
\r
561 System.out.println("<h1>FastCGI Hello! (Java)</h1>");
\r
562 System.out.println(
\r
563 "request number " + count + " running on host <i>" +
\r
564 System.getProperty("SERVER_NAME") + "</i>");
\r
570 <A NAME="S4">4. Running applications</A>
\r
573 <A NAME="S4.1">4.1 Using a Web server that supports FastCGI</A>
\r
576 For a current listing of Web servers that support FastCGI, see the <A HREF=
\r
577 "http://fastcgi.com">fastcgi.com</A> Web page.
\r
580 Some of the Web servers that support FastCGI perform management of FastCGI applications. You don't need to
\r
581 start and stop FastCGI applications; the Web server takes care of this. If an application process should
\r
582 crash, the Web server restarts it.
\r
585 Web servers support FastCGI via new configuration directives. Since these directives are server-specific, get
\r
586 more information from the documentation that accompanies each server.
\r
589 <A NAME="S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>
\r
592 The program <TT>cgi-fcgi</TT> allows you to run FastCGI applications using any Web server that supports CGI.
\r
595 Here is how <TT>cgi-fcgi</TT> works. <TT>cgi-fcgi</TT> is a standard CGI program that uses Unix domain or
\r
596 TCP/IP sockets to communicate with a FastCGI application. <TT>cgi-fcgi</TT> takes the path name or host/port
\r
597 name of a listening socket as a parameter and <TT>connect</TT>s to the FastCGI application listening on that
\r
598 socket. <TT>cgi-fcgi</TT> then forwards the CGI environment variables and <TT>stdin</TT> data to the FastCGI
\r
599 application, and forwards the <TT>stdout</TT> and <TT>stderr</TT> data from the FastCGI application to the Web
\r
600 server. When the FastCGI application signals the end of its response, <TT>cgi-fcgi</TT> flushes its buffers
\r
604 Obviously, having <TT>cgi-fcgi</TT> is not as good as having a server with integrated FastCGI support:
\r
608 Communication is slower than with a Web server that avoids the fork/exec overhead on every FastCGI request.
\r
611 <TT>cgi-fcgi</TT> does not perform application management, so you need to provide this yourself.
\r
614 <TT>cgi-fcgi</TT> supports only the Responder role.
\r
618 But <TT>cgi-fcgi</TT> does allow you to develop applications that retain state in memory between connections,
\r
619 which often provides a major performance boost over normal CGI. And all the applications you develop using
\r
620 <TT>cgi-fcgi</TT> will work with Web servers that have integrated support for FastCGI.
\r
623 The file <TT>examples/tiny-fcgi.cgi</TT> demonstrates a way to use <TT>cgi-fcgi</TT> to run a typical
\r
624 application, in this case the <TT>examples/tiny-fcgi</TT> application:
\r
627 #!../cgi-fcgi/cgi-fcgi -f
\r
628 -connect sockets/tiny-fcgi tiny-fcgi
\r
631 On most Unix platforms, executing this command-interpreter file runs <TT>cgi-fcgi</TT> with arguments
\r
632 <TT>-f</TT> and <TT>examples/tiny-fcgi.cgi</TT>. (Beware: On some Unix platforms, including HP-UX, the first
\r
633 line of a command-interpreter file cannot contain more than 32 characters, including the newline; you may need
\r
634 to install the <TT>cgi-fcgi</TT> application in a standard place like <TT>/usr/local/bin</TT> or create a
\r
635 symbolic link to the <TT>cgi-fcgi</TT> application in the directory containing your application.) The
\r
636 <TT>cgi-fcgi</TT> program reads the command-interpreter file and connects to the FastCGI application whose
\r
637 listening socket is <TT>examples/sockets/tiny-fcgi</TT>.
\r
640 Continuing the example, if <TT>cgi-fcgi</TT>'s connection attempt fails, it creates a new process running
\r
641 the program <TT>examples/tiny-fcgi</TT> and listening on socket <TT>examples/sockets/tiny-fcgi</TT>. Then
\r
642 <TT>cgi-fcgi</TT> retries the connection attempt, which now should succeed.
\r
645 The <TT>cgi-fcgi</TT> program has two other modes of operation. In one mode it connects to applications but
\r
646 does not start them; in the other it starts applications but does not connect to them. These modes are
\r
647 required when using TCP/IP. The <A HREF="cgi-fcgi.1"><TT>cgi-fcgi</TT> manpage</A>, <TT>doc/cgi-fcgi.1</TT>,
\r
648 tells the full story.
\r
651 To run the example applications using <TT>cgi-fcgi</TT>, start your Web server and give it the directory
\r
652 <TT>fcgi-devel-kit</TT> as the root of its URL space. If the machine running your server is called
\r
653 <TT>bowser</TT> and your server is running on port <TT>8888</TT>, you'd then open the URL
\r
654 <TT>http://bowser:8888/index.html</TT> to reach the kit's index page. Now the links on the index page that
\r
655 run example applications via <TT>cgi-fcgi</TT> should be active.
\r
658 <A NAME="S5">5. Known problems</A>
\r
661 On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file systems. The symptom
\r
662 when using cgi-fcgi is an exit status of 38 (<TT>ENOTSOCK</TT>: socket operation on non-socket), but cgi-fcgi
\r
663 may dump core in this case when compiled optimized. Work-around: Store your Unix domain listening sockets on a
\r
664 non NFS file system, upgrade to Digital UNIX 3.2, or use TCP sockets.
\r
667 On AIX there's a problem with shared listening sockets. The symptoms can include application core dumps
\r
668 and kernel panic. Work-around: Run a single FastCGI application server per listening socket.
\r
671 <A NAME="S6">6. Getting support</A>
\r
674 The mailing list <TT>fastcgi-developers@idle.com</TT> is used for discussions of issues in developing FastCGI
\r
675 applications. Topics include announcement of FastCGI-capable Web servers or changes to such servers,
\r
676 announcement of new application libraries or changes to such libraries, announcement of known bugs, discussion
\r
677 of design trade-offs in FastCGI application programming, and discussion of development plans and experiences.
\r
678 To join the list, send a message to <A HREF=
\r
679 "mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@idle.com</A> with a message body
\r
680 consisting of the word "subscribe" (leaving off the quotes).
\r
683 A link to a mail archive can be found on the FastCGI home page, <A HREF=
\r
684 "http://www.fastcgi.com">http://www.fastcgi.com</A>
\r
688 © 1996, Open Market, Inc. / mbrown@openmarket.com
\r
projects / catagits/fcgi2.git / blob