Commit | Line | Data |
0198fd3c |
1 | <html> |
0198fd3c |
2 | |
d39da662 |
3 | <head> |
4 | <title>FastCGI Developer's Kit</title> |
5 | </head> |
0198fd3c |
6 | |
d39da662 |
7 | <body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011" vlink="#555555"> |
0198fd3c |
8 | <a href="/fastcgi/words"> |
0198fd3c |
9 | |
d39da662 |
10 | <p align="center"><img border="0" src="/kit/images/fcgi-hd.gif" alt="[[FastCGI]]"></a> <br |
11 | clear="all"> |
12 | </p> |
13 | |
14 | <h3 align="center">FastCGI Developer's Kit</h3> |
0198fd3c |
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. --> |
18 | |
d39da662 |
19 | <p align="center">Mark R. Brown<br> |
0198fd3c |
20 | Open Market, Inc.<br> |
d39da662 |
21 | </p> |
0198fd3c |
22 | |
d39da662 |
23 | <p align="center">Document Version: 1.08<br> |
0198fd3c |
24 | 11 June 1996<br> |
d39da662 |
25 | </p> |
26 | |
27 | <h5 align="center">Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA |
28 | 02142 U.S.A.<br> |
29 | Tel: 617-621-9500 Fax: 617-621-1703 URL: <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br> |
30 | $Id: fcgi-devel-kit.htm,v 1.2 1999/02/06 06:15:11 roberts Exp $ <br> |
0198fd3c |
31 | </h5> |
d39da662 |
32 | |
0198fd3c |
33 | <hr> |
34 | |
d39da662 |
35 | <ul type="square"> |
36 | <li><a HREF="#S1">1. Introduction</a> </li> |
37 | <li><a HREF="#S2">2. Getting started</a> </li> |
38 | <li><a HREF="#S3">3. Writing applications</a> <ul type="square"> |
39 | <li><a HREF="#S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> </li> |
40 | <li><a HREF="#S3.2">3.2 Using the <tt>fcgiapp</tt> library</a> </li> |
41 | <li><a HREF="#S3.3">3.3 Using Perl and Tcl</a> </li> |
42 | <li><a HREF="#S3.4">3.4 Using Java</a> </li> |
43 | </ul> |
44 | </li> |
45 | <li><a HREF="#S4">4. Running applications</a> <ul type="square"> |
46 | <li><a HREF="#S4.1">4.1 Using a Web server that supports FastCGI</a> </li> |
47 | <li><a HREF="#S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a> </li> |
48 | </ul> |
49 | </li> |
50 | <li><a HREF="#S5">5. Known problems</a> </li> |
51 | <li><a HREF="#S6">6. Getting support</a> </li> |
0198fd3c |
52 | </ul> |
53 | |
54 | <hr> |
55 | |
d39da662 |
56 | <h3><a NAME="S1">1. Introduction</a></h3> |
0198fd3c |
57 | |
d39da662 |
58 | <p>FastCGI is an open extension to CGI that provides high performance for all Internet |
59 | applications without the penalties of Web server APIs.</p> |
0198fd3c |
60 | |
d39da662 |
61 | <p>FastCGI is designed to be layered on top of existing Web server APIs. For instance, the |
62 | <tt>mod_fastcgi</tt> Apache module adds FastCGI support to the Apache server. FastCGI can |
63 | also be used, with reduced functionality and reduced performance, on any Web server that |
64 | supports CGI.</p> |
0198fd3c |
65 | |
d39da662 |
66 | <p>This FastCGI Developer's Kit is designed to make developing FastCGI applications easy. |
67 | The kit currently supports FastCGI applications written in C/C++, Perl, Tcl, and Java.</p> |
0198fd3c |
68 | |
d39da662 |
69 | <p>This document: |
0198fd3c |
70 | |
d39da662 |
71 | <ul type="square"> |
72 | <li>Describes how to configure and build the kit for your development platform. </li> |
73 | <li>Tells how to write applications using the libraries in the kit. </li> |
74 | <li>Tells how to run applications using Web servers that support FastCGI or using any Web |
75 | server and <tt>cgi-fcgi</tt>. </li> |
0198fd3c |
76 | </ul> |
77 | |
d39da662 |
78 | <p>The kit includes a <a href="fastcgi-whitepaper/fastcgi.htm">technical white paper</a>, <tt>doc/fastcgi-whitepaper/fastcgi.htm</tt>. |
79 | You should read at least the first three sections of the technical white paper before |
80 | starting to write FastCGI applications. The <a href="fcgi-perf.htm">performance paper</a> |
81 | will help you understand how application design affects performance with FastCGI.</p> |
82 | |
83 | <p>The <a href="fcgi-spec.html">FastCGI Specification</a>, <tt>doc/fcgi-spec.html</tt>, |
84 | defines the interface between a FastCGI application and a Web server that supports |
85 | FastCGI. The software in the kit implements the specification. You don't need to read the |
86 | specification in order to write applications.</p> |
87 | |
88 | <p>Additional information is provided in the <a |
89 | href="http://www.fastcgi.com/words/FAQ.htm">FAQ</a> document, which contains frequently |
90 | asked questions about application development using FastCGI, as well as some general |
91 | information.</p> |
92 | |
93 | <p>Experience with CGI programming will be extremely valuable in writing FastCGI |
94 | applications. If you don't have enough experience with CGI programming, you should read |
95 | one of the popular books on the topic or study the <a |
96 | href="http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</a>. For a more formal treatment of |
97 | CGI/1.1 see the <a |
98 | href="http://ds.internic.net/internet-drafts/draft-robinson-www-interface-01.txt">Internet |
99 | Draft CGI 1.1 Specification</a>.</p> |
100 | |
101 | <h3><a NAME="S2">2. Getting started</a></h3> |
102 | |
103 | <p>The kit is a compressed tar (tar.Z) file, distributed via the <a |
104 | href="http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a> Web page. Unpacking the |
105 | tar file creates a new directory <tt>fcgi-devel-kit</tt>.</p> |
106 | |
107 | <p>Open the kit's index page, <tt>fcgi-devel-kit/index.html</tt>, using the "Open |
108 | File" command in your Web browser. The index page gives you an overview of the kit |
109 | structure and helps you navigate the kit. The index page also contains links that run some |
110 | example applications, but the applications won't work when index.html is opened using the |
111 | "Open File" command because they aren't aren't being accessed through a Web |
112 | server.</p> |
113 | |
114 | <p>In order to use the kit in earnest you'll need a Web server that you control, a Web |
115 | server running with your user ID. The Web server will be starting FastCGI applications |
116 | that you will need to debug; this will be a lot more convenient for you if these processes |
117 | run with your user ID. It is best to have a Web server that supports FastCGI. <a |
118 | href="#S4">Section 4</a> discusses Web server issues.</p> |
119 | |
120 | <p>If you can, keep the kit on a file system accessible from your personal workstation, do |
121 | your builds on your workstation, and run your Web server on your workstation. If that's |
122 | not possible, arrange a configuration such that the kit is accessible from the machine |
123 | that's going to run your Web server, and build the kit and your applications on a machine |
124 | that's configured exactly the same way (same processor architecture, operating system, |
125 | etc.) as the machine that's going to run your Web server.</p> |
126 | |
127 | <p>To build the kit you execute this sequence of commands in the <tt>fcgi-devel-kit</tt> |
128 | directory:</p> |
0198fd3c |
129 | |
130 | <pre> |
131 | % ./configure |
132 | % make |
133 | </pre> |
134 | |
d39da662 |
135 | <p>We've built and exercised the kit on these platforms (listed in alphabetical order): |
0198fd3c |
136 | |
d39da662 |
137 | <ul type="square"> |
138 | <li>BSD/OS 1.1 (Intel Pentium), gcc </li> |
139 | <li>Digital UNIX V3.2 148 (Alpha), gcc/cc </li> |
140 | <li>Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc </li> |
141 | <li>IBM AIX 1 4 (RS/6000), gcc </li> |
142 | <li>Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc </li> |
143 | <li>Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc </li> |
144 | <li>Sun SunOS 4.1.4 (SPARC), gcc </li> |
145 | </ul> |
0198fd3c |
146 | |
d39da662 |
147 | <p>Once you've built the kit, follow the directions in <a href="#S4">Section 4</a> to |
148 | bring up your Web server and run the example applications.</p> |
0198fd3c |
149 | |
d39da662 |
150 | <h3><a NAME="S3">3. Writing applications</a></h3> |
0198fd3c |
151 | |
d39da662 |
152 | <h4><a NAME="S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> </h4> |
0198fd3c |
153 | |
d39da662 |
154 | <p>The <tt>fcgi_stdio</tt> library provides the easiest transition for C CGI programs and |
155 | C CGI programmers to FastCGI. Using this library your application can run using either CGI |
156 | or FastCGI, with the same binary for both situations.</p> |
0198fd3c |
157 | |
d39da662 |
158 | <p>To introduce the <tt>fcgi_stdio</tt> library we give a pair of examples: a tiny CGI |
159 | program and the translation of this program to FastCGI. These two example programs are |
160 | included in the kit.</p> |
0198fd3c |
161 | |
d39da662 |
162 | <p>The CGI program is <tt>examples/tiny-cgi.c</tt>:</p> |
0198fd3c |
163 | |
164 | <pre> |
165 | #include <stdio.h> |
166 | #include <stdlib.h> |
167 | |
168 | void main(void) |
169 | { |
170 | int count = 0; |
d39da662 |
171 | printf("Content-type: text/html\r\n" |
172 | "\r\n" |
173 | "<title>CGI Hello!</title>" |
174 | "<h1>CGI Hello!</h1>" |
175 | "Request number %d running on host <i>%s</i>\n", |
176 | ++count, getenv("SERVER_NAME")); |
0198fd3c |
177 | } |
178 | </pre> |
179 | |
d39da662 |
180 | <p>The key features of this tiny CGI program are: |
181 | |
182 | <ul type="square"> |
183 | <li>The program sends data to the Web server by writing to <tt>stdout</tt>, using <tt>printf</tt> |
184 | in this example. The CGI program first sends a <tt>Content-type</tt> header, then a small |
185 | HTML document. The program includes <tt>stdio.h</tt> in order to get access to the <tt>printf</tt> |
186 | function.</li> |
187 | <li>The program obtains parameters provided by the Web server by reading environment |
188 | variables. The CGI program reads the <tt>SERVER_NAME</tt> variable using <tt>getenv</tt> |
189 | and includes the value in the HTML document. The program includes <tt>stdlib.h</tt> in |
190 | order to get access to the <tt>getenv</tt> function.</li> |
0198fd3c |
191 | </ul> |
192 | |
d39da662 |
193 | <p>The <tt>count</tt> variable is degenerate in this example; the CGI program runs a |
194 | single request, so the request number is always one. This variable will be more |
195 | interesting in the FastCGI example.</p> |
0198fd3c |
196 | |
d39da662 |
197 | <p><a NAME="S3.1.1">The</a> corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:</p> |
0198fd3c |
198 | |
199 | <pre> |
d39da662 |
200 | #include "fcgi_stdio.h" |
0198fd3c |
201 | #include <stdlib.h> |
202 | |
203 | void main(void) |
204 | { |
205 | int count = 0; |
206 | while(FCGI_Accept() >= 0) |
d39da662 |
207 | printf("Content-type: text/html\r\n" |
208 | "\r\n" |
209 | "<title>FastCGI Hello!</title>" |
210 | "<h1>FastCGI Hello!</h1>" |
211 | "Request number %d running on host <i>%s</i>\n", |
212 | ++count, getenv("SERVER_NAME")); |
0198fd3c |
213 | } |
214 | </pre> |
215 | |
d39da662 |
216 | <p>The key features of this tiny FastCGI program are: |
0198fd3c |
217 | |
d39da662 |
218 | <ul type="square"> |
219 | <li>The program is structured as a loop that begins by calling the function <tt>FCGI_Accept</tt>. |
220 | The <tt>FCGI_Accept</tt> function blocks until a new request arrives for the program to |
221 | execute. The program includes <tt>fcgi_stdio.h</tt> in order to get access to the <tt>FCGI_Accept</tt> |
222 | function.</li> |
223 | <li>Within the loop, <tt>FCGI_Accept</tt> creates a CGI-compatible world. <tt>printf</tt> |
224 | and <tt>getenv</tt> operate just as in the CGI program. <tt>stdin</tt> and <tt>stderr</tt>, |
225 | not used by this tiny program, also operate just as in a CGI program.</li> |
226 | </ul> |
0198fd3c |
227 | |
d39da662 |
228 | <p>The <tt>count</tt> variable increments each time through the loop, so the program |
229 | displays a new request number each time. You can use the reload button in your browser to |
230 | demonstrate this, once you've got the program built and running.</p> |
0198fd3c |
231 | |
232 | <h4>Building the program</h4> |
233 | |
d39da662 |
234 | <p>If you can build <tt>examples/tiny-cgi.c</tt>, it will be straightforward for you to |
235 | build <tt>examples/tiny-fcgi.c</tt>. You need to: |
236 | |
237 | <ul type="square"> |
238 | <li>Add the directory containing the <tt>fcgi_stdio.h</tt> header to the compiler's include |
239 | search path. The kit calls this directory <tt>include</tt>.</li> |
240 | <li>Add the library <tt>libfcgi.a</tt> to the linker's command line so that it will be |
241 | searched when linking. The <tt>libfcgi.a</tt> library implements the functions defined in <tt>fcgi_stdio.h</tt>. |
242 | The kit calls the directory containing this library <tt>libfcgi</tt>.</li> |
243 | <li>Determine whether or not the linker on your platform searches the Berkeley socket |
244 | library by default, and if not, add linker directives to force this search.</li> |
0198fd3c |
245 | </ul> |
246 | |
d39da662 |
247 | <p>See <tt>examples/Makefile</tt> (created by <tt>configure</tt>) for a Makefile that |
248 | builds both programs. Autoconf handles the platform-dependent linking issues; to see how, |
249 | examine <tt>configure.in</tt> and <tt>examples/Makefile.in</tt>.</p> |
0198fd3c |
250 | |
251 | <h4>Running the program</h4> |
d39da662 |
252 | <a href="#S4"> |
0198fd3c |
253 | |
d39da662 |
254 | <p>Section 4</a> is all about how to run FastCGI applications.</p> |
0198fd3c |
255 | |
d39da662 |
256 | <p>You can use CGI to run application binaries built with the <tt>fcgi_stdio</tt> library. |
257 | The <tt>FCGI_Accept</tt> function tests its environment to determine how the application |
258 | was invoked. If it was invoked as a CGI program, the first call to FCGI_Accept is |
259 | essentially a no-op and the second call returns <tt>-1</tt>. In effect, the request loop |
260 | disappears.</p> |
0198fd3c |
261 | |
d39da662 |
262 | <p>Of course, when a FastCGI application is run using CGI it does not get the benefits of |
263 | FastCGI. For instance, the application exits after servicing a single request, so it |
264 | cannot maintain cached information.</p> |
0198fd3c |
265 | |
266 | <h4>Implementation details</h4> |
d39da662 |
267 | <tt> |
268 | |
269 | <p>fcgi_stdio.h</tt> works by first including <tt>stdio.h</tt>, then defining macros to |
270 | replace essentially all of the types and procedures defined in <tt>stdio.h</tt>. (<tt>stdio.h</tt> |
271 | defines a few procedures that have nothing to do with <tt>FILE *</tt>, such as <tt>sprintf</tt> |
272 | and <tt>sscanf</tt>; <tt>fcgi_stdio.h</tt> doesn't replace these.) For instance, <tt>FILE</tt> |
273 | becomes <tt>FCGI_FILE</tt> and <tt>printf</tt> becomes <tt>FCGI_printf</tt>. You'll only |
274 | see these new names if you read <tt>fcgi_stdio.h</tt> or examine your C source code after |
275 | preprocessing.</p> |
276 | |
277 | <p>Here are some consequences of this implementation technique: |
278 | |
279 | <ul type="square"> |
280 | <li>On some platforms the implementation will break if you include <tt>stdio.h</tt> after |
281 | including <tt>fcgi_stdio.h</tt>, because <tt>stdio.h</tt> often defines macros for |
282 | functions such as <tt>getc</tt> and <tt>putc</tt>. Fortunately, on most platforms <tt>stdio.h</tt> |
283 | is protected against multiple includes by lines near the top of the file that look like <pre> |
0198fd3c |
284 | #ifndef _STDIO_H |
285 | #define _STDIO_H |
286 | </pre> |
d39da662 |
287 | <p>The specific symbol used for multiple-include protection, <tt>_STDIO_H</tt> in this |
288 | example, varies from platform to platform. As long as your platform protects <tt>stdio.h</tt> |
289 | against multiple includes, you can forget about this issue.</p> |
290 | </li> |
291 | <li>If your application passes <tt>FILE *</tt> to functions implemented in libraries for |
292 | which you have source code, then you'll want to recompile these libraries with <tt>fcgi_stdio.h</tt> |
293 | included. Most C compilers provide a command-line option for including headers in a |
294 | program being compiled; using such a compiler feature allows you to rebuild your libraries |
295 | without making source changes. For instance the gcc command line <pre> |
0198fd3c |
296 | gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c |
297 | </pre> |
d39da662 |
298 | <p>causes gcc to include <tt>fcgi_stdio.h</tt> before it even begins to read the module <tt>wonderlib.c</tt>.</p> |
299 | </li> |
300 | <li>If your application passes <tt>FILE *</tt> to functions implemented in libraries for |
301 | which you do not have source code, then you'll need to include the headers for these |
302 | libraries <i>before</i> you include <tt>fcgi_stdio.h</tt>. You can't pass the <tt>stdin</tt>, |
303 | <tt>stdout</tt>, or <tt>stderr</tt> streams produced by <tt>FCGI_Accept</tt> to any |
304 | functions implemented by these libraries. You can pass a stream on a Unix file to a |
305 | library function by following this pattern: <pre> |
306 | FILE *myStream = fopen(path, "r"); |
0198fd3c |
307 | answer = MungeStream(FCGI_ToFile(myStream)); |
308 | </pre> |
d39da662 |
309 | <p>Here <tt>MungeStream</tt> is a library function that you can't recompile and <tt>FCGI_ToFile</tt> |
310 | is a macro that converts from <tt>FCGI_FILE *</tt> to <tt>FILE *</tt>. The macro <tt>FCGI_ToFile</tt> |
311 | is defined in <tt>fcgi_stdio.h</tt>.</p> |
312 | </li> |
0198fd3c |
313 | </ul> |
314 | |
0198fd3c |
315 | <h4>Converting CGI programs</h4> |
316 | |
d39da662 |
317 | <p>The main task in converting a CGI program into a FastCGI program is separating the code |
318 | that needs to execute once, initializing the program, from the code that needs to run for |
319 | each request. In our tiny example, initializing the <tt>count</tt> variable is outside the |
320 | loop, while incrementing the <tt>count</tt> variable goes inside.</p> |
321 | |
322 | <p>Retained application state may be an issue. You must ensure that any application state |
323 | created in processing one request has no unintended effects on later requests. FastCGI |
324 | offers the possibility of significant application performance improvements, through |
325 | caching; it is up to you to make the caches work correctly.</p> |
0198fd3c |
326 | |
d39da662 |
327 | <p>Storage leaks may be an issue. Many CGI programs don't worry about storage leaks |
328 | because the programs don't run for long enough for bloating to be a problem. When |
329 | converting to FastCGI, you can either use a tool such as <a href="http://www.pure.com/"><i>Purify</i></a> |
330 | from Pure Software to discover and fix storage leaks, or you can run a C garbage collector |
331 | such as <a href="http://www.geodesic.com/"><i>Great Circle</i></a> from Geodesic Systems.</p> |
0198fd3c |
332 | |
333 | <h4>Limitations</h4> |
334 | |
d39da662 |
335 | <p>Currently there are some limits to the compatibility provided by the <tt>fcgi_stdio</tt> |
336 | library: |
337 | |
338 | <ul type="square"> |
339 | <li>The library does not provide FastCGI versions of the functions <tt>fscanf</tt> and <tt>scanf</tt>. |
340 | If you wish to apply <tt>fscanf</tt> or <tt>scanf</tt> to <tt>stdin</tt> of a FastCGI |
341 | program, the workaround is to read lines or other natural units into memory and then call <tt>sscanf</tt>. |
342 | If you wish to apply <tt>fscanf</tt> to a stream on a Unix file, the workaround is to |
343 | follow the pattern: <pre> |
344 | FILE *myStream = fopen(path, "r"); |
0198fd3c |
345 | count = fscanf(FCGI_ToFile(myStream), format, ...); |
346 | </pre> |
d39da662 |
347 | </li> |
0198fd3c |
348 | </ul> |
349 | |
350 | <h4>Reference documentation</h4> |
351 | |
d39da662 |
352 | <p>The <a href="FCGI_Accept.3"><tt>FCGI_Accept</tt> manpage</a>, <tt>doc/FCGI_Accept.3</tt>, |
353 | describes the function in the traditional format.</p> |
354 | |
355 | <p>The <a href="FCGI_Finish.3"><tt>FCGI_Finish</tt></a> (<tt>doc/FCGI_Finish.3</tt>), <a |
356 | href="FCGI_SetExitStatus.3"><tt>FCGI_SetExitStatus</tt></a> (<tt>doc/FCGI_SetExitStatus.3</tt>), |
357 | and <a href="FCGI_StartFilterData.3"><tt>FCGI_StartFilterData</tt></a> (<tt>doc/FCGI_StartFilterData.3</tt>) |
358 | manpages document capabilities of the <tt>fcgi-stdio</tt> library that are not illustrated |
359 | above.</p> |
360 | |
361 | <h4><a NAME="S3.2">3.2 Using the <tt>fcgiapp</tt> library</a></h4> |
362 | |
363 | <p>The <tt>fcgiapp</tt> library is a second C library for FastCGI. It does not provide the |
364 | high degree of source code compatibility provided by <tt>fcgi_stdio</tt>; in return, it |
365 | does not make such heavy use of <tt>#define</tt>. <tt>fcgi_stdio</tt> is implemented as a |
366 | thin layer on top of <tt>fcgiapp</tt>.</p> |
367 | |
368 | <p>Applications built using the <tt>fcgiapp</tt> library cannot run as CGI programs; that |
369 | feature is provided at the <tt>fcgi_stdio</tt> level.</p> |
370 | |
371 | <p>Functions defined in <tt>fcgiapp</tt> are named using the prefix <tt>FCGX_</tt> rather |
372 | than <tt>FCGI_</tt>. For instance, <tt>FCGX_Accept</tt> is the <tt>fcgiapp</tt> version of |
373 | <tt>FCGI_Accept</tt>.</p> |
374 | |
375 | <p>Documentation of the <tt>fcgiapp</tt> library takes the form of extensive comments in |
376 | the header file <tt>include/fcgiapp.h</tt>. The sample programs <tt>examples/tiny-fcgi2.c</tt> |
377 | and <tt>examples/echo2.c</tt> illustrate how to use <tt>fcgiapp</tt>.</p> |
378 | |
379 | <h4><a NAME="S3.3">3.3 Using Perl and Tcl</a></h4> |
380 | |
381 | <p>A major advantage of the FastCGI approach to high-performance Web applications is its |
382 | language-neutrality. CGI scripts written in popular languages such as Perl and Tcl can be |
383 | evolved into high-performance FastCGI applications.</p> |
384 | |
385 | <p>We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since |
386 | Perl and Tcl are conventional C applications and <tt>fcgi_stdio</tt> was designed for |
387 | converting conventional C applications. Essentially no source code changes were required |
388 | in these programs; a small amount of code was added in order to make <tt>FCGI_Accept</tt> |
389 | and other FastCGI primitives available in these languages. And because these interpreters |
390 | were developed using <tt>fcgi_stdio</tt>, they run standard Perl and Tcl applications |
391 | (e.g. CGI scripts) as well as FastCGI applications.</p> |
392 | |
393 | <p>See the <a href="http://www.fastcgi.com/applibs/">www.fastcgi.com/applibs</a> Web page |
394 | for downloadable Perl and Tcl binaries for selected platforms. Because many users of Perl |
395 | and Tcl run extended versions of these languages, the kit includes separate companion |
396 | documents describing <a href="fcgi-perl.htm">how to build FastCGI-integrated Perl</a> and <a |
397 | href="fcgi-tcl.htm">how to build FastCGI-integrated Tcl</a>.</p> |
398 | |
399 | <p>Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:</p> |
400 | |
0198fd3c |
401 | <pre> |
402 | #!./perl |
403 | use FCGI; |
404 | $count = 0; |
d39da662 |
405 | while(FCGI::accept() >= 0) { |
406 | print("Content-type: text/html\r\n\r\n", |
407 | "<title>FastCGI Hello! (Perl)</title>\n", |
408 | "<h1>FastCGI Hello! (Perl)</h1>\n"; |
409 | "Request number ", ++$count, |
410 | " running on host <i>";$env(SERVER_NAME)</i>"); |
0198fd3c |
411 | } |
412 | </pre> |
413 | |
414 | <pre> |
415 | #!./tclsh |
416 | set count 0 |
417 | while {[FCGI_Accept] >= 0 } { |
418 | incr count |
d39da662 |
419 | puts -nonewline "Content-type: text/html\r\n\r\n" |
420 | puts "<title>FastCGI Hello! (Tcl)</title>" |
421 | puts "<h1>FastCGI Hello! (Tcl)</h1>" |
422 | puts "Request number $count running on host <i>$env(SERVER_NAME)</i>" |
0198fd3c |
423 | } |
424 | </pre> |
425 | |
d39da662 |
426 | <p>Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from |
427 | converting a C CGI application to FastCGI. You separate the portion of the application |
428 | that performs one-time initialization from the portion that performs per-request |
429 | processing. You put the per-request processing into a loop controlled by <tt>FCGI::accept</tt> |
430 | (Perl) or <tt>FCGI_Accept</tt> (Tcl). </p> |
0198fd3c |
431 | |
d39da662 |
432 | <h4><a NAME="S3.4">3.4 Using Java</a></h4> |
0198fd3c |
433 | |
d39da662 |
434 | <p>Java is not just for browser-based applets. It is already suitable for writing some Web |
435 | server applications, and its range of applicability will only grow as Java compilers and |
436 | other Java tools improve. Java's modules, garbage collection, and threads are especially |
437 | valuable for writing long-lived application servers.</p> |
0198fd3c |
438 | |
d39da662 |
439 | <p>The <tt>FCGIInterface</tt> class provides facilities for Java applications analogous to |
440 | what <tt>fcgi_stdio</tt> provides for C applications. Using this library your Java |
441 | application can run using either CGI or FastCGI.</p> |
0198fd3c |
442 | |
d39da662 |
443 | <p>The kit includes separate companion document on <a href="fcgi-java.htm">using FastCGI |
444 | with Java</a>. The source code for FastCGI classes is contained in directory <tt>java/src</tt> |
445 | and the compiled code in <tt>java/classes</tt>.</p> |
0198fd3c |
446 | |
d39da662 |
447 | <p>Here is the Java version of <tt>tiny-fcgi</tt>:</p> |
0198fd3c |
448 | |
449 | <pre> |
450 | import FCGIInterface; |
451 | |
452 | class TinyFCGI { |
453 | public static void main (String args[]) { |
454 | int count = 0; |
d39da662 |
455 | while(new FCGIInterface().FCGIaccept()>= 0) { |
0198fd3c |
456 | count ++; |
d39da662 |
457 | System.out.println("Content-type: text/html\r\n\r\n"); |
0198fd3c |
458 | System.out.println( |
d39da662 |
459 | "<title>FastCGI Hello! (Java)</title>"); |
460 | System.out.println("<h1>FastCGI Hello! (Java)</h1>"); |
0198fd3c |
461 | System.out.println( |
d39da662 |
462 | "request number " + count + " running on host <i>" + |
463 | System.getProperty("SERVER_NAME") + "</i>"); |
0198fd3c |
464 | } |
465 | } |
466 | } |
467 | </pre> |
0198fd3c |
468 | |
d39da662 |
469 | <h3><a NAME="S4">4. Running applications</a></h3> |
0198fd3c |
470 | |
d39da662 |
471 | <h3><a NAME="S4.1">4.1 Using a Web server that supports FastCGI</a></h3> |
0198fd3c |
472 | |
d39da662 |
473 | <p>For a current listing of Web servers that support FastCGI, see the <a |
474 | HREF="http://www.fastcgi.com/servers">www.fastcgi.com/servers</a> Web page.</p> |
0198fd3c |
475 | |
d39da662 |
476 | <p>All of the Web servers that support FastCGI perform management of FastCGI applications. |
477 | You don't need to start and stop FastCGI applications; the Web server takes care of this. |
478 | If an application process should crash, the Web server restarts it.</p> |
0198fd3c |
479 | |
d39da662 |
480 | <p>Web servers support FastCGI via new configuration directives. Since these directives |
481 | are server-specific, get more information from the documentation that accompanies each |
482 | server.</p> |
0198fd3c |
483 | |
d39da662 |
484 | <p>The directory <a HREF="../examples/conf"><tt>examples/conf</tt></a> contains config |
485 | files designed to run the example programs included in the FastCGI Developer's Kit. Each |
486 | config file contains specific installation instructions.</p> |
0198fd3c |
487 | |
d39da662 |
488 | <p>The more advanced example programs take advantage of special features of the Open |
489 | Market Secure WebServer, such as anonymous ticketing and support for the Authorizer role. |
490 | If you don't have this server, download a <a |
491 | HREF="http://www.openmarket.com/store/eval/swsg.htm">free evaluation copy</a> to run the |
492 | examples.</p> |
0198fd3c |
493 | |
d39da662 |
494 | <h3><a NAME="S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3> |
0198fd3c |
495 | |
d39da662 |
496 | <p>The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications using any Web |
497 | server that supports CGI.</p> |
0198fd3c |
498 | |
d39da662 |
499 | <p>Here is how <tt>cgi-fcgi</tt> works. <tt>cgi-fcgi</tt> is a standard CGI program that |
500 | uses Unix domain or TCP/IP sockets to communicate with a FastCGI application. <tt>cgi-fcgi</tt> |
501 | takes the path name or host/port name of a listening socket as a parameter and <tt>connect</tt>s |
502 | to the FastCGI application listening on that socket. <tt>cgi-fcgi</tt> then forwards the |
503 | CGI environment variables and <tt>stdin</tt> data to the FastCGI application, and forwards |
504 | the <tt>stdout</tt> and <tt>stderr</tt> data from the FastCGI application to the Web |
505 | server. When the FastCGI application signals the end of its response, <tt>cgi-fcgi</tt> |
506 | flushes its buffers and exits.</p> |
0198fd3c |
507 | |
d39da662 |
508 | <p>Obviously, having <tt>cgi-fcgi</tt> is not as good as having a server with integrated |
509 | FastCGI support: |
0198fd3c |
510 | |
511 | <ul> |
d39da662 |
512 | <li>Communication is slower than with a Web server that avoids the fork/exec overhead on |
513 | every FastCGI request. </li> |
514 | <li><tt>cgi-fcgi</tt> does not perform application management, so you need to provide this |
515 | yourself. </li> |
516 | <li><tt>cgi-fcgi</tt> supports only the Responder role. </li> |
0198fd3c |
517 | </ul> |
518 | |
d39da662 |
519 | <p>But <tt>cgi-fcgi</tt> does allow you to develop applications that retain state in |
520 | memory between connections, which often provides a major performance boost over normal |
521 | CGI. And all the applications you develop using <tt>cgi-fcgi</tt> will work with Web |
522 | servers that have integrated support for FastCGI.</p> |
0198fd3c |
523 | |
d39da662 |
524 | <p>The file <tt>examples/tiny-fcgi.cgi</tt> demonstrates a way to use <tt>cgi-fcgi</tt> to |
525 | run a typical application, in this case the <tt>examples/tiny-fcgi</tt> application: </p> |
0198fd3c |
526 | |
527 | <pre> |
528 | #!../cgi-fcgi/cgi-fcgi -f |
529 | -connect sockets/tiny-fcgi tiny-fcgi |
530 | </pre> |
531 | |
d39da662 |
532 | <p>On most Unix platforms, executing this command-interpreter file runs <tt>cgi-fcgi</tt> |
533 | with arguments <tt>-f</tt> and <tt>examples/tiny-fcgi.cgi</tt>. (Beware: On some Unix |
534 | platforms, including HP-UX, the first line of a command-interpreter file cannot contain |
535 | more than 32 characters, including the newline; you may need to install the <tt>cgi-fcgi</tt> |
536 | application in a standard place like <tt>/usr/local/bin</tt> or create a symbolic link to |
537 | the <tt>cgi-fcgi</tt> application in the directory containing your application.) The <tt>cgi-fcgi</tt> |
538 | program reads the command-interpreter file and connects to the FastCGI application whose |
539 | listening socket is <tt>examples/sockets/tiny-fcgi</tt>.</p> |
540 | |
541 | <p>Continuing the example, if <tt>cgi-fcgi</tt>'s connection attempt fails, it creates a |
542 | new process running the program <tt>examples/tiny-fcgi</tt> and listening on socket <tt>examples/sockets/tiny-fcgi</tt>. |
543 | Then <tt>cgi-fcgi</tt> retries the connection attempt, which now should succeed.</p> |
544 | |
545 | <p>The <tt>cgi-fcgi</tt> program has two other modes of operation. In one mode it connects |
546 | to applications but does not start them; in the other it starts applications but does not |
547 | connect to them. These modes are required when using TCP/IP. The <a href="cgi-fcgi.1"><tt>cgi-fcgi</tt> |
548 | manpage</a>, <tt>doc/cgi-fcgi.1</tt>, tells the full story.</p> |
549 | |
550 | <p>To run the example applications using <tt>cgi-fcgi</tt>, start your Web server and give |
551 | it the directory <tt>fcgi-devel-kit</tt> as the root of its URL space. If the machine |
552 | running your server is called <tt>bowser</tt> and your server is running on port <tt>8888</tt>, |
553 | you'd then open the URL <tt>http://bowser:8888/index.html</tt> to reach the kit's index |
554 | page. Now the links on the index page that run example applications via <tt>cgi-fcgi</tt> |
555 | should be active.</p> |
556 | |
557 | <h3><a NAME="S5">5. Known problems</a></h3> |
558 | |
559 | <p>On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file |
560 | systems. The symptom when using cgi-fcgi is an exit status of 38 (<tt>ENOTSOCK</tt>: |
561 | socket operation on non-socket), but cgi-fcgi may dump core in this case when compiled |
562 | optimized. Work-around: Store your Unix domain listening sockets on a non NFS file system, |
563 | upgrade to Digital UNIX 3.2, or use TCP sockets.</p> |
564 | |
565 | <p>On AIX there's a problem with shared listening sockets. The symptoms can include |
566 | application core dumps and kernel panic. Work-around: Run a single FastCGI application |
567 | server per listening socket.</p> |
568 | |
569 | <h3><a NAME="S6">6. Getting support</a></h3> |
570 | |
571 | <p>The mailing list <tt>fastcgi-developers@idle.com</tt> is used for discussions of issues |
572 | in developing FastCGI applications. Topics include announcement of FastCGI-capable Web |
573 | servers or changes to such servers, announcement of new application libraries or changes |
574 | to such libraries, announcement of known bugs, discussion of design trade-offs in FastCGI |
575 | application programming, and discussion of development plans and experiences. To join the |
576 | list, send a message to <a href="mailto:fastcgi-developers-request@openmarket.com">fastcgi-developers-request@idle.com</a> |
577 | with a message body consisting of the word "subscribe" (leaving off the quotes).</p> |
578 | |
579 | <p>A link to a mail archive can be found on the FastCGI home page, <a |
580 | href="http://www.fastcgi.com">http://www.fastcgi.com</a></p> |
0198fd3c |
581 | |
582 | <hr> |
583 | |
584 | <address> |
d39da662 |
585 | © 1996, Open Market, Inc. / mbrown@openmarket.com |
0198fd3c |
586 | </address> |
0198fd3c |
587 | </body> |
588 | </html> |