Commit | Line | Data |
0198fd3c |
1 | FastCGI Developer's Kit |
2 | /fastcgi/words |
3 | fcgi-hd.gif |
4 | [FastCGI] |
5 | <center>FastCGI Developer's Kit</center> |
6 | |
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. --> |
10 | |
11 | <center> |
12 | Mark R. Brown<br> |
13 | Open Market, Inc.<br> |
14 | <p> |
15 | |
16 | Document Version: 1.08<br> |
17 | 11 June 1996<br> |
18 | </center> |
19 | <p> |
20 | |
21 | <h5 align=center> |
22 | Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, |
23 | MA 02142 U.S.A.<br> |
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> |
27 | </h5> |
28 | <hr> |
29 | |
30 | <ul type=square> |
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> |
34 | <ul type=square> |
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> |
39 | </ul> |
40 | <li><a HREF = "#S4">4. Running applications</a> |
41 | <ul type=square> |
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> |
44 | </ul> |
45 | <li><a HREF = "#S5">5. Known problems</a> |
46 | <li><a HREF = "#S6">6. Getting support</a> |
47 | </ul> |
48 | |
49 | <hr> |
50 | |
51 | |
52 | |
53 | <h3><a NAME = "S1">1. Introduction</a></h3> |
54 | |
55 | FastCGI is an open extension to CGI that provides high performance |
56 | for all Internet applications without the penalties of Web server |
57 | APIs.<p> |
58 | |
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 |
63 | that supports CGI.<p> |
64 | |
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> |
68 | |
69 | This document: |
70 | |
71 | <ul type=square> |
72 | <li>Describes how to configure and build the |
73 | kit for your development platform. |
74 | |
75 | <li>Tells how to write applications using the |
76 | libraries in the kit. |
77 | |
78 | <li>Tells how to run applications using Web servers that support |
79 | FastCGI or using any Web server and <tt>cgi-fcgi</tt>. |
80 | </ul> |
81 | |
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> |
88 | |
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> |
94 | |
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> |
99 | |
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> |
106 | |
107 | |
108 | |
109 | <h3><a NAME = "S2">2. Getting started</a></h3> |
110 | |
111 | The kit is a compressed tar (tar.Z) file, |
112 | distributed via the |
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> |
116 | |
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 |
123 | server.<p> |
124 | |
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> |
131 | |
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> |
140 | |
141 | To build the kit you execute this sequence of commands |
142 | in the <tt>fcgi-devel-kit</tt> directory:<p> |
143 | |
144 | <pre> |
145 | % ./configure |
146 | % make |
147 | </pre> |
148 | |
149 | We've built and exercised the kit on these platforms |
150 | (listed in alphabetical order):<p> |
151 | |
152 | <ul type=square> |
153 | <li> |
154 | BSD/OS 1.1 (Intel Pentium), gcc |
155 | <li> |
156 | Digital UNIX V3.2 148 (Alpha), gcc/cc |
157 | <li> |
158 | Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc |
159 | <li> |
160 | IBM AIX 1 4 (RS/6000), gcc |
161 | <li> |
162 | Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc |
163 | <li> |
164 | Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc |
165 | <li> |
166 | Sun SunOS 4.1.4 (SPARC), gcc |
167 | </ul> |
168 | |
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> |
172 | |
173 | |
174 | |
175 | <h3><a NAME = "S3">3. Writing applications</a></h3> |
176 | |
177 | |
178 | <h4><a NAME = "S3.1">3.1 Using the <tt>fcgi_stdio</tt> library</a> |
179 | </h4> |
180 | |
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> |
186 | |
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> |
190 | |
191 | The CGI program is <tt>examples/tiny-cgi.c</tt>:<p> |
192 | |
193 | <pre> |
194 | #include <stdio.h> |
195 | #include <stdlib.h> |
196 | |
197 | void main(void) |
198 | { |
199 | int count = 0; |
200 | printf("Content-type: text/html\r\n" |
201 | "\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")); |
206 | } |
207 | </pre> |
208 | |
209 | The key features of this tiny CGI program are:<p> |
210 | |
211 | <ul type = square> |
212 | <li> |
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> |
218 | <li> |
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> |
225 | </ul> |
226 | |
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> |
231 | |
232 | <a NAME = "S3.1.1">The</a> |
233 | corresponding FastCGI program is <tt>examples/tiny-fcgi.c</tt>:<p> |
234 | |
235 | <pre> |
236 | #include "fcgi_stdio.h" |
237 | #include <stdlib.h> |
238 | |
239 | void main(void) |
240 | { |
241 | int count = 0; |
242 | while(FCGI_Accept() >= 0) |
243 | printf("Content-type: text/html\r\n" |
244 | "\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")); |
249 | } |
250 | </pre> |
251 | |
252 | The key features of this tiny FastCGI program are:<p> |
253 | |
254 | <ul type = square> |
255 | <li> |
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> |
261 | <li> |
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> |
267 | </ul> |
268 | |
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> |
273 | |
274 | |
275 | <h4>Building the program</h4> |
276 | |
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> |
280 | |
281 | <ul type = square> |
282 | <li> |
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> |
286 | <li> |
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> |
292 | <li> |
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> |
297 | </ul> |
298 | |
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> |
304 | |
305 | |
306 | <h4>Running the program</h4> |
307 | |
308 | <a href = "#S4">Section 4</a> is all about |
309 | how to run FastCGI applications.<p> |
310 | |
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> |
317 | |
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> |
322 | |
323 | |
324 | <h4>Implementation details</h4> |
325 | |
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> |
335 | |
336 | Here are some |
337 | consequences of this implementation technique:<p> |
338 | |
339 | <ul type = square> |
340 | <li> |
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 |
347 | <pre> |
348 | #ifndef _STDIO_H |
349 | #define _STDIO_H |
350 | </pre> |
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> |
355 | <li> |
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 |
364 | <pre> |
365 | gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c |
366 | </pre> |
367 | causes gcc to include <tt>fcgi_stdio.h</tt> before it even |
368 | begins to read the module <tt>wonderlib.c</tt>.<p> |
369 | <li> |
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: |
380 | <pre> |
381 | FILE *myStream = fopen(path, "r"); |
382 | answer = MungeStream(FCGI_ToFile(myStream)); |
383 | </pre> |
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> |
388 | </ul> |
389 | |
390 | |
391 | <h4>Converting CGI programs</h4> |
392 | |
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 |
398 | goes inside.<p> |
399 | |
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 |
405 | correctly.<p> |
406 | |
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> |
416 | |
417 | |
418 | <h4>Limitations</h4> |
419 | |
420 | Currently there are some limits to the compatibility provided |
421 | by the <tt>fcgi_stdio</tt> library:<p> |
422 | |
423 | <ul type = square> |
424 | <li> |
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: |
432 | <pre> |
433 | FILE *myStream = fopen(path, "r"); |
434 | count = fscanf(FCGI_ToFile(myStream), format, ...); |
435 | </pre> |
436 | </ul> |
437 | |
438 | <h4>Reference documentation</h4> |
439 | |
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 |
442 | format.<p> |
443 | |
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> |
452 | |
453 | |
454 | <h4><a NAME = "S3.2">3.2 Using the <tt>fcgiapp</tt> library</a></h4> |
455 | |
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> |
461 | |
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> |
464 | level.<p> |
465 | |
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> |
470 | |
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 |
475 | <tt>fcgiapp</tt>.<p> |
476 | |
477 | |
478 | <h4><a NAME = "S3.3">3.3 Using Perl and Tcl</a></h4> |
479 | |
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> |
484 | |
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> |
495 | |
496 | See the |
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> |
503 | |
504 | Here are the Perl and Tcl versions of <tt>tiny-fcgi</tt>:<p> |
505 | <pre> |
506 | #!./perl |
507 | use FCGI; |
508 | $count = 0; |
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>"); |
515 | } |
516 | </pre> |
517 | |
518 | <pre> |
519 | #!./tclsh |
520 | set count 0 |
521 | while {[FCGI_Accept] >= 0 } { |
522 | incr count |
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>" |
527 | } |
528 | </pre> |
529 | |
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> |
536 | (Tcl). |
537 | |
538 | |
539 | |
540 | <h4><a NAME = "S3.4">3.4 Using Java</a></h4> |
541 | |
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> |
547 | |
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> |
552 | |
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> |
558 | |
559 | Here is the Java version of <tt>tiny-fcgi</tt>:<p> |
560 | |
561 | <pre> |
562 | import FCGIInterface; |
563 | |
564 | class TinyFCGI { |
565 | public static void main (String args[]) { |
566 | int count = 0; |
567 | while(new FCGIInterface().FCGIaccept()>= 0) { |
568 | count ++; |
569 | System.out.println("Content-type: text/html\r\n\r\n"); |
570 | System.out.println( |
571 | "<title>FastCGI Hello! (Java)</title>"); |
572 | System.out.println("<h1>FastCGI Hello! (Java)</h1>"); |
573 | System.out.println( |
574 | "request number " + count + " running on host <i>" + |
575 | System.getProperty("SERVER_NAME") + "</i>"); |
576 | } |
577 | } |
578 | } |
579 | </pre> |
580 | <p> |
581 | |
582 | |
583 | <h3><a NAME = "S4">4. Running applications</a></h3> |
584 | |
585 | |
586 | <h3><a NAME = "S4.1">4.1 Using a Web server that supports FastCGI</a></h3> |
587 | |
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> |
590 | Web page.<p> |
591 | |
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> |
596 | |
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> |
600 | |
601 | The directory |
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 |
605 | instructions.<p> |
606 | |
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, |
610 | download a |
611 | <a HREF= "http://www.openmarket.com/store/eval/swsg.htm">free |
612 | evaluation copy</a> to run the examples.<p> |
613 | |
614 | |
615 | <h3><a NAME = "S4.2">4.2 Using <tt>cgi-fcgi</tt> with any Web server</a></h3> |
616 | |
617 | The program <tt>cgi-fcgi</tt> allows you to run FastCGI applications |
618 | using any Web server that supports CGI.<p> |
619 | |
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 |
622 | to communicate with |
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> |
632 | |
633 | Obviously, having <tt>cgi-fcgi</tt> is not as good as having |
634 | a server with integrated FastCGI support:<p> |
635 | |
636 | <ul> |
637 | <li>Communication is slower than with a Web server that avoids the |
638 | fork/exec overhead on every FastCGI request. |
639 | |
640 | <li><tt>cgi-fcgi</tt> does not perform application management, |
641 | so you need to provide this yourself. |
642 | |
643 | <li><tt>cgi-fcgi</tt> supports only the Responder role. |
644 | </ul> |
645 | |
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 |
651 | FastCGI.<p> |
652 | |
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: |
656 | |
657 | <pre> |
658 | #!../cgi-fcgi/cgi-fcgi -f |
659 | -connect sockets/tiny-fcgi tiny-fcgi |
660 | </pre> |
661 | |
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 |
670 | your application.) |
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> |
674 | |
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> |
681 | |
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> |
688 | |
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> |
696 | |
697 | |
698 | |
699 | <h3><a NAME = "S5">5. Known problems</a></h3> |
700 | |
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 |
707 | TCP sockets.<p> |
708 | |
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 |
712 | socket.<p> |
713 | |
714 | |
715 | |
716 | <h3><a NAME = "S6">6. Getting support</a></h3> |
717 | |
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> |
729 | |
730 | Mail sent to this list is archived and available on the |
731 | World-Wide Web at |
732 | <pre> |
733 | http://www.fastcgi.com/mail/ |
734 | </pre> |
735 | |
736 | Open Market Secure WebServer customers get FastCGI |
737 | support where they get server support.<p> |
738 | |
739 | |
740 | |
741 | <hr> |
742 | |
743 | <address> |
744 | © 1996, Open Market, Inc. / mbrown@openmarket.com |
745 | </address> |
746 | |