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