1 FastCGI Developer's Kit
5 <center>FastCGI Developer's Kit</center>
7 <!--Copyright (c) 1996 Open Market, Inc. -->
8 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
9 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
16 Document Version: 1.08<br>
22 Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
24 Tel: 617-621-9500 Fax: 617-621-1703 URL:
25 <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
26 $Id: fcgi-devel-kit.gut,v 1.1 1997/09/16 15:36:26 stanleyg Exp $ <br>
31 <li><a HREF = "#S1">1. Introduction</a>
32 <li><a HREF = "#S2">2. Getting started</a>
33 <li><a HREF = "#S3">3. Writing applications</a>
35 <li><a HREF = "#S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a>
36 <li><a HREF = "#S3.2">3.2 Using the <tt>fcgiapp</tt> library</a>
37 <li><a HREF = "#S3.3">3.3 Using Perl and Tcl</a>
38 <li><a HREF = "#S3.4">3.4 Using Java</a>
40 <li><a HREF = "#S4">4. Running applications</a>
42 <li><a HREF = "#S4.1">4.1 Using a Web server that supports FastCGI</a>
43 <li><a HREF = "#S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a>
45 <li><a HREF = "#S5">5. Known problems</a>
46 <li><a HREF = "#S6">6. Getting support</a>
53 <h3><a NAME = "S1">1. Introduction</a></h3>
55 FastCGI is an open extension to CGI that provides high performance
56 for all Internet applications without the penalties of Web server
59 FastCGI is designed to be layered on top of existing Web server
60 APIs. For instance, the <tt>mod_fastcgi</tt> Apache module adds
61 FastCGI support to the Apache server. FastCGI can also be used,
62 with reduced functionality and reduced performance, on any Web server
65 This FastCGI Developer's Kit is designed to make developing FastCGI
66 applications easy. The kit currently supports FastCGI
67 applications written in C/C++, Perl, Tcl, and Java.<p>
72 <li>Describes how to configure and build the
73 kit for your development platform.
75 <li>Tells how to write applications using the
78 <li>Tells how to run applications using Web servers that support
79 FastCGI or using any Web server and <tt>cgi-fcgi</tt>.
82 The kit includes a <a href="fastcgi-whitepaper/fastcgi.htm">technical white
83 paper</a>, <tt>doc/fastcgi-whitepaper/fastcgi.htm</tt>.
84 You should read at least the first three sections of the
85 technical white paper before starting to write FastCGI applications.
86 The <a href="fcgi-perf.htm">performance paper</a> will help you understand
87 how application design affects performance with FastCGI.<p>
89 The <a href ="fcgi-spec.html">FastCGI Specification</a>,
90 <tt>doc/fcgi-spec.html</tt>, defines the interface between a FastCGI
91 application and a Web server that supports FastCGI. The software in
92 the kit implements the specification. You don't need to
93 read the specification in order to write applications.<p>
95 Additional information is provided in the
96 <a href ="http://www.fastcgi.com/words/FAQ.htm">FAQ</a> document, which
97 contains frequently asked questions about application development
98 using FastCGI, as well as some general information.<p>
100 Experience with CGI programming will be extremely valuable in writing FastCGI
101 applications. If you don't have enough experience with CGI programming,
102 you should read one of the popular books on the topic or study the
103 <a href = "http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</a>.
104 For a more formal treatment of CGI/1.1 see the
105 <a href = "http://ds.internic.net/internet-drafts/draft-robinson-www-interface-01.txt">Internet Draft CGI 1.1 Specification</a>.<p>
109 <h3><a NAME = "S2">2. Getting started</a></h3>
111 The kit is a compressed tar (tar.Z) file,
113 <a href = "http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a>
114 Web page. Unpacking the tar file creates a new directory
115 <tt>fcgi-devel-kit</tt>.<p>
117 Open the kit's index page, <tt>fcgi-devel-kit/index.html</tt>, using
118 the "Open File" command in your Web browser. The index page gives you
119 an overview of the kit structure and helps you navigate the kit. The
120 index page also contains links that run some example applications, but
121 the applications won't work when index.html is opened using the "Open
122 File" command because they aren't aren't being accessed through a Web
125 In order to use the kit in earnest you'll need a Web server that you
126 control, a Web server running with your user ID. The Web server will
127 be starting FastCGI applications that you will need to debug; this
128 will be a lot more convenient for you if these processes run with your
129 user ID. It is best to have a Web server that supports FastCGI.
130 <a href = "#S4">Section 4</a> discusses Web server issues.<p>
132 If you can, keep the kit on a file system accessible from your
133 personal workstation, do your builds on your workstation, and run your
134 Web server on your workstation. If that's not possible, arrange a
135 configuration such that the kit is accessible from the machine that's
136 going to run your Web server, and build the kit and your applications
137 on a machine that's configured exactly the same way (same processor
138 architecture, operating system, etc.) as the machine that's going to
139 run your Web server.<p>
141 To build the kit you execute this sequence of commands
142 in the <tt>fcgi-devel-kit</tt> directory:<p>
149 We've built and exercised the kit on these platforms
150 (listed in alphabetical order):<p>
154 BSD/OS 1.1 (Intel Pentium), gcc
156 Digital UNIX V3.2 148 (Alpha), gcc/cc
158 Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc
160 IBM AIX 1 4 (RS/6000), gcc
162 Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc
164 Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc
166 Sun SunOS 4.1.4 (SPARC), gcc
169 Once you've built the kit, follow the directions in
170 <a href = "#S4">Section 4</a> to bring up your Web server
171 and run the example applications.<p>
175 <h3><a NAME = "S3">3. Writing applications</a></h3>
178 <h4><a NAME = "S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a>
181 The <tt>fcgi_stdio</tt> library provides
182 the easiest transition for C CGI programs and C CGI
183 programmers to FastCGI. Using this library your application
184 can run using either CGI or FastCGI, with the same binary
185 for both situations.<p>
187 To introduce the <tt>fcgi_stdio</tt> library
188 we give a pair of examples: a tiny CGI program and the translation of this
189 program to FastCGI. These two example programs are included in the kit.<p>
191 The CGI program is <tt>examples/tiny-cgi.c</tt>:<p>
194 #include <stdio.h>
195 #include <stdlib.h>
200 printf("Content-type: text/html\r\n"
202 "<title>CGI Hello!</title>"
203 "<h1>CGI Hello!</h1>"
204 "Request number %d running on host <i>%s</i>\n",
205 ++count, getenv("SERVER_NAME"));
209 The key features of this tiny CGI program are:<p>
213 The program sends data to the Web server by writing to
214 <tt>stdout</tt>, using <tt>printf</tt> in this example. The CGI
215 program first sends a <tt>Content-type</tt> header, then a
216 small HTML document. The program includes <tt>stdio.h</tt> in
217 order to get access to the <tt>printf</tt> function.<p>
219 The program obtains parameters provided by the Web server by
220 reading environment variables. The CGI program reads the
221 <tt>SERVER_NAME</tt> variable using <tt>getenv</tt> and
222 includes the value in the HTML document. The program includes
223 <tt>stdlib.h</tt> in order to get access to the
224 <tt>getenv</tt> function.<p>
227 The <tt>count</tt> variable is degenerate in this example;
228 the CGI program runs a single request, so the request number
229 is always one. This variable will be more interesting
230 in the FastCGI example.<p>
232 <a NAME = "S3.1.1">The</a>
233 corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:<p>
236 #include "fcgi_stdio.h"
237 #include <stdlib.h>
242 while(FCGI_Accept() >= 0)
243 printf("Content-type: text/html\r\n"
245 "<title>FastCGI Hello!</title>"
246 "<h1>FastCGI Hello!</h1>"
247 "Request number %d running on host <i>%s</i>\n",
248 ++count, getenv("SERVER_NAME"));
252 The key features of this tiny FastCGI program are:<p>
256 The program is structured as a loop that begins by calling the
257 function <tt>FCGI_Accept</tt>. The <tt>FCGI_Accept</tt>
258 function blocks until a new request arrives for the program to
259 execute. The program includes <tt>fcgi_stdio.h</tt> in order
260 to get access to the <tt>FCGI_Accept</tt> function.<p>
262 Within the loop, <tt>FCGI_Accept</tt> creates a
263 CGI-compatible world. <tt>printf</tt> and <tt>getenv</tt>
264 operate just as in the CGI program. <tt>stdin</tt> and
265 <tt>stderr</tt>, not used by this tiny program, also
266 operate just as in a CGI program.<p>
269 The <tt>count</tt> variable increments each time through the loop, so
270 the program displays a new request number each time. You can use
271 the reload button in your browser to demonstrate this, once you've
272 got the program built and running.<p>
275 <h4>Building the program</h4>
277 If you can build <tt>examples/tiny-cgi.c</tt>,
278 it will be straightforward for you to build
279 <tt>examples/tiny-fcgi.c</tt>. You need to:<p>
283 Add the directory containing the
284 <tt>fcgi_stdio.h</tt> header to the compiler's include search
285 path. The kit calls this directory <tt>include</tt>.<p>
287 Add the library <tt>libfcgi.a</tt> to the linker's command
288 line so that it will be searched when linking. The
289 <tt>libfcgi.a</tt> library implements the functions defined in
290 <tt>fcgi_stdio.h</tt>. The kit calls the directory containing
291 this library <tt>libfcgi</tt>.<p>
293 Determine whether or not the linker on your
294 platform searches the Berkeley socket
295 library by default, and if not, add linker directives to
296 force this search.<p>
299 See <tt>examples/Makefile</tt> (created by <tt>configure</tt>)
300 for a Makefile that builds both
301 programs. Autoconf handles the platform-dependent linking issues; to
302 see how, examine <tt>configure.in</tt> and
303 <tt>examples/Makefile.in</tt>.<p>
306 <h4>Running the program</h4>
308 <a href = "#S4">Section 4</a> is all about
309 how to run FastCGI applications.<p>
311 You can use CGI to run application binaries built with the
312 <tt>fcgi_stdio</tt> library. The <tt>FCGI_Accept</tt>
313 function tests its environment to determine how the application was
314 invoked. If it was invoked as a CGI program, the first
315 call to FCGI_Accept is essentially a no-op and the second call
316 returns <tt>-1</tt>. In effect, the request loop disappears.<p>
318 Of course, when a FastCGI application is run using CGI it does not
319 get the benefits of FastCGI. For instance, the application exits
320 after servicing a single request, so it cannot maintain
321 cached information.<p>
324 <h4>Implementation details</h4>
326 <tt>fcgi_stdio.h</tt> works by first including <tt>stdio.h</tt>, then
327 defining macros to replace essentially all of the types and procedures
328 defined in <tt>stdio.h</tt>. (<tt>stdio.h</tt> defines a few
329 procedures that have nothing to do with <tt>FILE *</tt>, such as
330 <tt>sprintf</tt> and <tt>sscanf</tt>; <tt>fcgi_stdio.h</tt> doesn't
331 replace these.) For instance, <tt>FILE</tt> becomes
332 <tt>FCGI_FILE</tt> and <tt>printf</tt> becomes <tt>FCGI_printf</tt>.
333 You'll only see these new names if you read <tt>fcgi_stdio.h</tt> or
334 examine your C source code after preprocessing.<p>
337 consequences of this implementation technique:<p>
341 On some platforms the implementation will break if you include
342 <tt>stdio.h</tt> after including <tt>fcgi_stdio.h</tt>,
343 because <tt>stdio.h</tt> often defines macros for functions such
344 as <tt>getc</tt> and <tt>putc</tt>. Fortunately, on most
345 platforms <tt>stdio.h</tt> is protected against multiple
346 includes by lines near the top of the file that look like
351 The specific symbol used for multiple-include protection,
352 <tt>_STDIO_H</tt> in this example, varies from platform to
353 platform. As long as your platform protects <tt>stdio.h</tt>
354 against multiple includes, you can forget about this issue.<p>
356 If your application passes <tt>FILE *</tt> to functions
357 implemented in libraries for which you have source code, then
358 you'll want to recompile these
359 libraries with <tt>fcgi_stdio.h</tt> included.
360 Most C compilers provide a command-line option for including
361 headers in a program being compiled; using such a compiler feature
362 allows you to rebuild your libraries without making source changes.
363 For instance the gcc command line
365 gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c
367 causes gcc to include <tt>fcgi_stdio.h</tt> before it even
368 begins to read the module <tt>wonderlib.c</tt>.<p>
370 If your application passes <tt>FILE *</tt> to functions
371 implemented in libraries
372 for which you do not have source code, then
373 you'll need to include the headers for these libraries
374 <i>before</i> you include <tt>fcgi_stdio.h</tt>.
375 You can't pass the <tt>stdin</tt>,
376 <tt>stdout</tt>, or <tt>stderr</tt> streams produced by
377 <tt>FCGI_Accept</tt> to any functions implemented by these
378 libraries. You can pass a stream on a Unix file to a library
379 function by following this pattern:
381 FILE *myStream = fopen(path, "r");
382 answer = MungeStream(FCGI_ToFile(myStream));
384 Here <tt>MungeStream</tt> is a library function that you can't
385 recompile and <tt>FCGI_ToFile</tt> is a macro that converts
386 from <tt>FCGI_FILE *</tt> to <tt>FILE *</tt>. The macro
387 <tt>FCGI_ToFile</tt> is defined in <tt>fcgi_stdio.h</tt>.<p>
391 <h4>Converting CGI programs</h4>
393 The main task in converting a CGI program into a FastCGI program is
394 separating the code that needs to execute once, initializing the
395 program, from the code that needs to run for each request.
396 In our tiny example, initializing the <tt>count</tt> variable
397 is outside the loop, while incrementing the <tt>count</tt> variable
400 Retained application state may be an issue. You must ensure that
401 any application state created in processing one request has no
402 unintended effects on later requests. FastCGI offers the possibility
403 of significant application performance improvements, through caching;
404 it is up to you to make the caches work
407 Storage leaks may be an issue. Many CGI programs don't worry about
408 storage leaks because the programs don't run for long enough for
409 bloating to be a problem. When converting to FastCGI, you
410 can either use a tool such as
411 <a href ="http://www.pure.com/"><i>Purify</i></a> from Pure Software
412 to discover and fix storage
413 leaks, or you can run a C garbage collector such as
414 <a href ="http://www.geodesic.com/"><i>Great Circle</i></a>
415 from Geodesic Systems.<p>
420 Currently there are some limits to the compatibility provided
421 by the <tt>fcgi_stdio</tt> library:<p>
425 The library does not provide FastCGI versions of
426 the functions <tt>fscanf</tt> and <tt>scanf</tt>. If you wish
427 to apply <tt>fscanf</tt> or <tt>scanf</tt> to <tt>stdin</tt>
428 of a FastCGI program, the workaround is to read lines or other
429 natural units into memory and then call <tt>sscanf</tt>. If
430 you wish to apply <tt>fscanf</tt> to a stream on a Unix file,
431 the workaround is to follow the pattern:
433 FILE *myStream = fopen(path, "r");
434 count = fscanf(FCGI_ToFile(myStream), format, ...);
438 <h4>Reference documentation</h4>
440 The <a href = "FCGI_Accept.3"><tt>FCGI_Accept</tt> manpage</a>,
441 <tt>doc/FCGI_Accept.3</tt>, describes the function in the traditional
444 The <a href = "FCGI_Finish.3"><tt>FCGI_Finish</tt></a>
445 (<tt>doc/FCGI_Finish.3</tt>),
446 <a href = "FCGI_SetExitStatus.3"><tt>FCGI_SetExitStatus</tt></a>
447 (<tt>doc/FCGI_SetExitStatus.3</tt>), and
448 <a href = "FCGI_StartFilterData.3"><tt>FCGI_StartFilterData</tt></a>
449 (<tt>doc/FCGI_StartFilterData.3</tt>)
450 manpages document capabilities of the <tt>fcgi-stdio</tt>
451 library that are not illustrated above.<p>
454 <h4><a NAME = "S3.2">3.2 Using the <tt>fcgiapp</tt> library</a></h4>
456 The <tt>fcgiapp</tt> library is a second C library for FastCGI. It
457 does not provide the high degree of source code compatibility provided
458 by <tt>fcgi_stdio</tt>; in return, it does not make such heavy use of
459 <tt>#define</tt>. <tt>fcgi_stdio</tt> is implemented as
460 a thin layer on top of <tt>fcgiapp</tt>.<p>
462 Applications built using the <tt>fcgiapp</tt> library cannot run
463 as CGI programs; that feature is provided at the <tt>fcgi_stdio</tt>
466 Functions defined in <tt>fcgiapp</tt> are named using the prefix
467 <tt>FCGX_</tt> rather than <tt>FCGI_</tt>. For instance,
468 <tt>FCGX_Accept</tt> is the <tt>fcgiapp</tt> version of
469 <tt>FCGI_Accept</tt>.<p>
471 Documentation of the <tt>fcgiapp</tt> library takes the form
472 of extensive comments in the header file <tt>include/fcgiapp.h</tt>.
473 The sample programs <tt>examples/tiny-fcgi2.c</tt> and
474 <tt>examples/echo2.c</tt> illustrate how to use
478 <h4><a NAME = "S3.3">3.3 Using Perl and Tcl</a></h4>
480 A major advantage of the FastCGI approach to high-performance Web
481 applications is its language-neutrality. CGI scripts written in
482 popular languages such as Perl and Tcl can be evolved into
483 high-performance FastCGI applications.<p>
485 We have produced FastCGI-integrated Perl and Tcl
486 interpreters. Doing so was easy, since Perl and Tcl
487 are conventional C applications and <tt>fcgi_stdio</tt> was
488 designed for converting conventional C applications. Essentially no source
489 code changes were required in these programs; a small amount
490 of code was added in order to make <tt>FCGI_Accept</tt> and other
491 FastCGI primitives available in these languages. And because
492 these interpreters were developed using <tt>fcgi_stdio</tt>, they
493 run standard Perl and Tcl applications (e.g. CGI scripts) as well
494 as FastCGI applications.<p>
497 <a href = "http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a>
498 Web page for downloadable Perl and Tcl binaries for selected platforms.
499 Because many users of Perl and Tcl run extended versions of these languages,
500 the kit includes separate companion documents describing
501 <a href ="fcgi-perl.htm">how to build FastCGI-integrated Perl</a>
502 and <a href ="fcgi-tcl.htm">how to build FastCGI-integrated Tcl</a>.<p>
504 Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:<p>
509 while(FCGI::accept() >= 0) {
510 print("Content-type: text/html\r\n\r\n",
511 "<title>FastCGI Hello! (Perl)</title>\n",
512 "<h1>FastCGI Hello! (Perl)</h1>\n";
513 "Request number ", ++$count,
514 " running on host <i>";$env(SERVER_NAME)</i>");
521 while {[FCGI_Accept] >= 0 } {
523 puts -nonewline "Content-type: text/html\r\n\r\n"
524 puts "<title>FastCGI Hello! (Tcl)</title>"
525 puts "<h1>FastCGI Hello! (Tcl)</h1>"
526 puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
530 Converting a Perl or Tcl CGI application to FastCGI is not fundamentally
531 different from converting a C CGI application to FastCGI. You separate
532 the portion of the application that performs one-time
533 initialization from the portion that performs per-request
534 processing. You put the per-request processing into a loop
535 controlled by <tt>FCGI::accept</tt> (Perl) or <tt>FCGI_Accept</tt>
540 <h4><a NAME = "S3.4">3.4 Using Java</a></h4>
542 Java is not just for browser-based applets. It is already suitable for
543 writing some Web server applications, and its range of applicability will
544 only grow as Java compilers and other Java tools improve. Java's
545 modules, garbage collection, and threads are especially valuable
546 for writing long-lived application servers.<p>
548 The <tt>FCGIInterface</tt> class provides facilities for Java
549 applications analogous to what <tt>fcgi_stdio</tt> provides for C
550 applications. Using this library your Java application can run using
551 either CGI or FastCGI.<p>
553 The kit includes separate companion document on
554 <a href ="fcgi-java.htm">using FastCGI with Java</a>. The
555 source code for FastCGI classes is contained in
556 directory <tt>java/src</tt>
557 and the compiled code in <tt>java/classes</tt>.<p>
559 Here is the Java version of <tt>tiny-fcgi</tt>:<p>
562 import FCGIInterface;
565 public static void main (String args[]) {
567 while(new FCGIInterface().FCGIaccept()>= 0) {
569 System.out.println("Content-type: text/html\r\n\r\n");
571 "<title>FastCGI Hello! (Java)</title>");
572 System.out.println("<h1>FastCGI Hello! (Java)</h1>");
574 "request number " + count + " running on host <i>" +
575 System.getProperty("SERVER_NAME") + "</i>");
583 <h3><a NAME = "S4">4. Running applications</a></h3>
586 <h3><a NAME = "S4.1">4.1 Using a Web server that supports FastCGI</a></h3>
588 For a current listing of Web servers that support FastCGI,
589 see the <a HREF = "http://www.fastcgi.com/servers">www.fastcgi.com/servers</a>
592 All of the Web servers that support FastCGI perform management of
593 FastCGI applications. You don't need to start and stop FastCGI
594 applications; the Web server takes care of this. If an application
595 process should crash, the Web server restarts it.<p>
597 Web servers support FastCGI via new configuration directives.
598 Since these directives are server-specific, get more information
599 from the documentation that accompanies each server.<p>
602 <a HREF = "../examples/conf"><tt>examples/conf</tt></a> contains config
603 files designed to run the example programs included in the FastCGI
604 Developer's Kit. Each config file contains specific installation
607 The more advanced example programs take advantage of special features
608 of the Open Market Secure WebServer, such as anonymous ticketing
609 and support for the Authorizer role. If you don't have this server,
611 <a HREF= "http://www.openmarket.com/store/eval/swsg.htm">free
612 evaluation copy</a> to run the examples.<p>
615 <h3><a NAME = "S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3>
617 The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications
618 using any Web server that supports CGI.<p>
620 Here is how <tt>cgi-fcgi</tt> works. <tt>cgi-fcgi</tt> is a
621 standard CGI program that uses Unix domain or TCP/IP sockets
623 a FastCGI application. <tt>cgi-fcgi</tt> takes the path name
624 or host/port name of a
625 listening socket as a parameter and <tt>connect</tt>s to the FastCGI
626 application listening on that socket. <tt>cgi-fcgi</tt> then forwards the CGI
627 environment variables and <tt>stdin</tt> data to the FastCGI
628 application, and forwards the <tt>stdout</tt> and <tt>stderr</tt> data
629 from the FastCGI application to the Web server. When the FastCGI
630 application signals the end of its response, <tt>cgi-fcgi</tt> flushes
631 its buffers and exits.<p>
633 Obviously, having <tt>cgi-fcgi</tt> is not as good as having
634 a server with integrated FastCGI support:<p>
637 <li>Communication is slower than with a Web server that avoids the
638 fork/exec overhead on every FastCGI request.
640 <li><tt>cgi-fcgi</tt> does not perform application management,
641 so you need to provide this yourself.
643 <li><tt>cgi-fcgi</tt> supports only the Responder role.
646 But <tt>cgi-fcgi</tt> does allow you to
647 develop applications that retain state in memory between connections,
648 which often provides a major performance boost over normal CGI. And
649 all the applications you develop using <tt>cgi-fcgi</tt>
650 will work with Web servers that have integrated support for
653 The file <tt>examples/tiny-fcgi.cgi</tt> demonstrates
654 a way to use <tt>cgi-fcgi</tt> to run a typical application,
655 in this case the <tt>examples/tiny-fcgi</tt> application:
658 #!../cgi-fcgi/cgi-fcgi -f
659 -connect sockets/tiny-fcgi tiny-fcgi
662 On most Unix platforms, executing this command-interpreter file runs
663 <tt>cgi-fcgi</tt> with arguments <tt>-f</tt> and
664 <tt>examples/tiny-fcgi.cgi</tt>. (Beware: On some
665 Unix platforms, including HP-UX, the first line of a command-interpreter file
666 cannot contain more than 32 characters, including the newline;
667 you may need to install the <tt>cgi-fcgi</tt> application in a standard
668 place like <tt>/usr/local/bin</tt> or create a symbolic link
669 to the <tt>cgi-fcgi</tt> application in the directory containing
671 The <tt>cgi-fcgi</tt> program reads the command-interpreter file and
672 connects to the FastCGI application whose listening socket is
673 <tt>examples/sockets/tiny-fcgi</tt>.<p>
675 Continuing the example, if
676 <tt>cgi-fcgi</tt>'s connection attempt fails, it
677 creates a new process
678 running the program <tt>examples/tiny-fcgi</tt> and listening on
679 socket <tt>examples/sockets/tiny-fcgi</tt>. Then <tt>cgi-fcgi</tt>
680 retries the connection attempt, which now should succeed.<p>
682 The <tt>cgi-fcgi</tt> program has two other modes of operation.
683 In one mode it connects to applications but does not start them;
684 in the other it starts applications but does not connect
685 to them. These modes are required when using TCP/IP. The
686 <a href = "cgi-fcgi.1"><tt>cgi-fcgi</tt> manpage</a>,
687 <tt>doc/cgi-fcgi.1</tt>, tells the full story.<p>
689 To run the example applications using <tt>cgi-fcgi</tt>, start your
690 Web server and give it the directory <tt>fcgi-devel-kit</tt> as the
691 root of its URL space. If the machine running your server is called
692 <tt>bowser</tt> and your server is running on port <tt>8888</tt>,
693 you'd then open the URL <tt>http://bowser:8888/index.html</tt> to
694 reach the kit's index page. Now the links on the index page that run
695 example applications via <tt>cgi-fcgi</tt> should be active.<p>
699 <h3><a NAME = "S5">5. Known problems</a></h3>
701 On Digital UNIX 3.0 there's a problem with Unix domain listening
702 sockets on NFS file systems. The symptom when using cgi-fcgi is an
703 exit status of 38 (<tt>ENOTSOCK</tt>: socket operation on non-socket),
704 but cgi-fcgi may dump core in this case when compiled optimized.
705 Work-around: Store your Unix domain listening
706 sockets on a non NFS file system, upgrade to Digital UNIX 3.2, or use
709 On AIX there's a problem with shared listening sockets.
710 The symptoms can include application core dumps and kernel panic.
711 Work-around: Run a single FastCGI application server per listening
716 <h3><a NAME = "S6">6. Getting support</a></h3>
718 The mailing list <tt>fastcgi-developers@openmarket.com</tt>
719 is used for discussions of issues in developing FastCGI applications.
720 Topics include announcement of FastCGI-capable Web servers or
721 changes to such servers, announcement of new application libraries
722 or changes to such libraries, announcement of known bugs, discussion
723 of design trade-offs in FastCGI application programming, and discussion
724 of development plans and experiences. To join the
725 list, send a message to
726 <a href = "mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@openmarket.com</a>
727 with a message body consisting of the word "subscribe"
728 (leaving off the quotes).<p>
730 Mail sent to this list is archived and available on the
733 http://www.fastcgi.com/mail/
736 Open Market Secure WebServer customers get FastCGI
737 support where they get server support.<p>
744 © 1996, Open Market, Inc. / mbrown@openmarket.com